Skip to content

CONSTITUTION.md

Latest commit

 

History

History
251 lines (192 loc) · 6.25 KB

CONSTITUTION.md

File metadata and controls

251 lines (192 loc) · 6.25 KB
Raw

OpenCortex 项目宪法

本文档定义 OpenCortex 项目的基本开发规则和约定，所有参与项目的人员必须遵守

第一条：阅读并更新 Memory 文件 ⭐

规则：

  • 每次开始工作前，必须先阅读 MEMORY.md
  • 每次重大变更后，必须立即更新 MEMORY.md
  • 更新内容包括：功能变更、技术决策、Bug 修复、版本发布

执行方式：

  1. 打开项目时：cat MEMORY.md
  2. 完成工作后：更新 ## 📅 日期 (版本号) 章节
  3. 记录：核心变更、原因、实施方案、修改文件、测试结果

第二条：更新文档 📚

规则：

  • 添加新功能：必须更新 docs/ 下对应的技术文档
  • 修改 API：必须更新 docs/03-Linear接入方案.md 或 docs/04-GitHub接入方案.md
  • 修改数据库：必须更新 docs/06-数据库设计.md
  • 修改 Prompt：必须更新 docs/05-LLM提取方案.md

文档结构：

docs/
├── README.md              # 文档导航
├── 01-快速入门.md         # 项目简介
├── 02-技术架构.md         # 系统架构
├── 03-Linear接入方案.md   # Linear API
├── 04-GitHub接入方案.md   # GitHub Webhook
├── 05-LLM提取方案.md      # 知识提取
├── 06-数据库设计.md       # 数据结构
└── 07-实施计划.md         # 开发计划

第三条：理解产品约束 🎯

核心约束（必须遵守）：

  1. 产品定位：AI-native 团队知识中枢

    • 不是笔记工具，不是知识库软件
    • 是自动捕获、结构化、维护知识的系统

  2. 核心价值："AI 写，人审核"

    • 知识自动生长，用户几乎不需要手动输入
    • 与 Notion AI "人写，AI 辅助" 模式完全相反

  3. 目标用户：10-50人的小型技术团队

    • 不是个人，不是大企业
    • 专注中国/亚洲技术团队

  4. 简单原则：零配置，开箱即用

    • 用户不需要建任何东西
    • 接入数据源后自动工作

  5. 渐进式开发：

    • Phase 0：静默收集（不打扰团队）
    • Phase 1：查询界面（查询知识）
    • Phase 2：主动推送（每天汇总）

第四条：代码质量标准 💻

代码规范：

  • Python 代码遵循 PEP 8
  • 使用类型注解（Type Hints）
  • 函数必须有文档字符串（Docstring）
  • 关键逻辑必须有注释

命名规范：

  • 变量：snake_case（如：linear_client）
  • 函数：snake_case（如：fetch_issues()）
  • 类：PascalCase（如：LinearConnector）
  • 常量：UPPER_CASE（如：API_BASE_URL）

代码审查：

  • 所有代码必须经过审查才能合并
  • 审查重点：逻辑正确性、性能、安全性

第五条：安全与隐私 🔐

敏感信息处理：

  • 所有敏感信息（API Key、Token）记录到 key.md
  • key.md 添加到 .gitignore，绝不提交到 Git
  • 代码中使用环境变量加载敏感信息

用户隐私：

  • 不收集用户个人隐私数据
  • 只收集团队公开的工作信息（Linear issue、GitHub PR）
  • 数据加密存储

安全规则：

  • 不在代码中硬编码任何密钥
  • 不在日志中打印敏感信息
  • API 调用必须使用 HTTPS

第六条：版本号管理 📌

版本号规则（语义化版本）：

  • 格式：vMAJOR.MINOR.PATCH
  • MAJOR：重大架构变更
  • MINOR：新功能添加
  • PATCH：Bug 修复

每次修改必须更新版本号，并同步更新以下位置：

  1. MEMORY.md 的 当前版本 字段
  2. MEMORY.md 的 📅 日期 (版本号) 章节
  3. Git commit message（如：feat: add Linear connector (v0.2.0)）
  4. 如有发布，更新 package.json 或 __version__.py

版本号示例：

  • v0.1.0 - 项目启动，建立基础设施
  • v0.2.0 - 完成 Linear API 接入
  • v0.3.0 - 完成 GitHub Webhook 接入
  • v1.0.0 - Phase 0 完成，开始产品化

第七条：开发流程检查清单 ✅

开始开发前

  • 阅读 MEMORY.md 了解项目历史
  • 阅读 CONSTITUTION.md 了解开发规范
  • 阅读相关技术文档（docs/ 目录）
  • 确认任务优先级和实施计划

开发过程中

  • 代码符合 PEP 8 规范
  • 关键逻辑有注释
  • 敏感信息记录到 key.md
  • 不在代码中硬编码密钥

开发完成后

  • 更新 MEMORY.md 记录变更
  • 更新相关技术文档
  • 更新版本号
  • 测试功能是否正常
  • 提交 Git commit

第八条：敏感信息记录 🔑

记录位置：/Users/xiaolin/Downloads/同步空间/OpenCortex/key.md

记录模板：

### [服务名称]
**类型**: API Key / Token / AccessKey
**用途**: [说明用途]
**时间**: YYYY-MM-DD
**敏感信息**:

[实际的key]

**环境变量名**: LINEAR_API_KEY

记录时机：

  • 申请到新的 API Key
  • 配置 Webhook Secret
  • 获取数据库密码
  • 任何需要保密的信息

安全规则：

  • ❌ 不要提交到 Git 仓库
  • ✅ 添加到 .gitignore
  • ✅ 使用环境变量加载
  • ✅ 定期轮换密钥

第九条：API 设计原则 🌐

RESTful 风格：

  • 使用标准 HTTP 方法（GET、POST、PUT、DELETE）
  • URL 使用名词，不用动词
  • 返回标准 HTTP 状态码

响应格式：

{
  "success": true,
  "data": { ... },
  "error": null
}

错误处理：

{
  "success": false,
  "data": null,
  "error": {
    "code": "LINEAR_API_ERROR",
    "message": "Linear API 认证失败"
  }
}

分页：

  • 使用 page 和 page_size 参数
  • 返回总数和分页信息

第十条：测试要求 🧪

单元测试：

  • 核心函数必须有单元测试
  • 测试覆盖率目标：≥ 70%

集成测试：

  • API 接入脚本需要集成测试
  • 使用 Mock 数据测试

手动测试：

  • 每次发布前必须手动测试完整流程
  • 记录测试结果到 MEMORY.md

附录：项目核心约束速查

约束 说明
产品定位 AI-native 团队知识中枢
核心价值 "AI 写，人审核"
目标用户 10-50人小型技术团队
简单原则 零配置，开箱即用
数据源 Linear + GitHub + 飞书
技术栈 Python + SQLite + LLM

最后更新: 2026-03-10 版本: v1.0 制定人: Claude Code + 晓力