先从文档导航找到任务相关说明；coding agent 还应读取适用的 AGENTS。开发环境、验证命令和真实调用边界统一见开发指南。
- Fork the repository or branch from current
main. Follow the README for prerequisites, then runnpm ciandnpm run build. - For documentation changes, run
npm run verify:docs; for code changes, runnpm run check. Tests read built output indist/, so build before running individual tests. Default checks do not call paid models; real Runtime checks require explicit opt-in. - Update the relevant documentation and open a PR using the template. Describe the user impact, checks actually run and anything unverified. Most technical documentation is currently in Chinese; English contributions and questions are welcome.
Small fixes can go directly to a PR. For larger changes, discuss scope in Issues first. Useful starting points include documentation corrections and synthetic regression fixtures; contributing does not require paid model calls. Never include credentials or unsanitized private sessions. Use the security policy for vulnerabilities and follow the code of conduct.
- Fork 或创建分支 — 在 GitHub 上 fork 仓库，或从最新
main创建功能分支。 - 安装与构建 —
npm ci、npm run build（见中文 README）。 - 选择验证 — 文档改动跑
npm run verify:docs；代码改动跑npm run check（见开发指南）。默认验证不调用计费模型。 - 更新唯一文档归宿 — 用户行为改 使用指南；架构不变量改 架构；未完成目标改 路线图。
- 发 PR — 使用 PR 模板，说明影响、验证命令与未验证事项。
小修（措辞、示例、单测）可以直接 PR。较大方向（新 Runtime、持久化格式、工具面变化）建议先在 Issue 中简述范围，避免未经确认的大规模重构。不必为每次贡献通读全部 ADR 与门禁脚本。
适合首次贡献的方向：
- 文档示例与链接修复（如本文档系列）
- 合成 fixture 回归测试（
test/fixtures/） - 平台验证记录（授权环境下的 smoke 输出与失败项说明）
只有仓库中已存在且适合公开参与的任务才应链接；不要未经检查标注「good first issue」。外部贡献默认不要求花费模型费用。
明确用户问题、改动范围和完成条件；区分当前缺陷与目标能力。做最小可验证改动，同批更新行为的唯一文档归宿。小修无需独立 Issue、计划或 ADR。
较大任务可以在已有任务说明中记录：Goal、范围与非目标、Done means（可观察完成条件）、Verification（实际命令与结果）、Rollback（撤回与数据兼容）。这是可选简报，不要求新建文件。跨会话恢复优先使用已有 Issue 或任务记录。
使用 PR 模板，说明用户影响、验证和未验证事项。按需链接相关决策或说明无契约变化；用户可见变化更新 CHANGELOG。生成区改源后生成，不能直接改产物。
审查依次关注范围与必要性、模块所有者、失败及安全边界、验证证据和简化机会。代码与文档冲突时追实际行为和设计依据；不能用过期规范要求实现倒退，也不能删除产品要求来掩盖 bug。
维护者 @caulif 负责合入和发布。CODEOWNERS 是审查路由，不代表平台已配置强制审批，也不授予发布权限。项目没有委员会或固定发布周期；贡献数量和 Agent 身份不自动带来管理权限。
跨模块协议、持久化格式、提示词契约、工具权限、架构边界或工程流程发生变化时，同批更新或新增记录，说明真实考虑过的替代方案；格式与历史检索见 ADR。普通样式微调、函数拆分和措辞修正无需单独记录。门禁变化仍须满足反向用例要求，不降低覆盖率阈值。
- 当前用户行为归使用指南；模块职责与不变量归架构；未完成目标和缺失证据归路线图；理由归 ADR。目录与受控边界见结构约定。
- 一份事实只有一个归宿，别处使用相对链接。字段、枚举、默认值、prompt 和工具定义以代码或生成区为准；可保留经过核对的短操作示例。
- 当前文档写实际行为、边界和失败语义。历史决定保留当时正文，失效部分标明后继；不能把历史归档当作同时有效的规范。
- 合并或移动时修复所有入站和出站链接、生成器目标、门禁配置与所有者路径。完成后运行文档检查；门禁不能替代语义核对。
- 一次性讨论与证据放本地忽略目录，不让公开文档依赖它们。沿用现有材料，避免为每次任务再建一篇总计划。
不提交凭据、真实会话或未经脱敏的实验材料。漏洞走安全政策，普通支持见中文 README，社区行为见行为准则。发布与数据回退见开发指南。交接说明实际权限、剩余风险与未完成验证，不能把无人回应视作接管授权。