贡献指南

1. 开发环境搭建
2. 使用 beans 管理工作计划
3. 智能体指引
4. 文档
5. 交付变更

---

开发环境搭建

git clone https://github.com/litlfred/folio-assistant.git
cd folio-assistant
bun install
bun test          # 单元测试
bun run cat lint      # eslint
bun run cat test:e2e      # 端到端测试 (test:e2e)

使用 beans 管理工作计划

本项目使用 beans 作为唯一的待办事项/工作计划机制（参见 AGENTS.md）。切勿另外建立独立的待办事项存储。

scripts/install-beans.sh
beans list
beans create "<title>"
beans <id> --status in-progress   # 开始工作前先认领

beans ≠ sidecars：切勿对机器批量生成的队列（QA、witness、watcher）使用 beans create——这些应保留为批量 JSON。

智能体指引

AGENTS.md 是通用的智能体单一事实来源（Claude Code、Gemini CLI、Antigravity、Cursor、Copilot 均原生支持读取）。CLAUDE.md / GEMINI.md 是指向它的轻量存根。当修改智能体指引时，请更新 AGENTS.md 而非针对特定工具的文件。

文档

• 说明文档位于 docs/ 下（即本 Jekyll 站点）。

• 技能模式参考是自动生成的——切勿手动编辑 docs/reference/skills/*.md。请编辑 schemas/skills/<skill>/ 下的 JSON Schema 并重新生成：

  bun run scripts/gen-schema-docs.ts
  

• 技能指令（docs/reference/skill-instructions/*.md）也是自动生成的——切勿手动编辑。请编辑 skills/authoring/content-lifecycle/*.md 或 src/skills/*.md 下的技能正文并重新生成：

  bun run scripts/gen-skill-docs.ts
  

• TypeScript API 参考（/api/）由 CI 中的 TypeDoc 自动生成。
• 每次推送到 main 且涉及文档、模式或源码的提交，都会由 .github/workflows/docs-site.yml 自动构建该站点并部署到 GitHub Pages。

本地预览：

cd docs
bundle install
bundle exec jekyll serve

交付变更

验证 → 确认可合并 → 推送 →（仅在被要求时）发起 PR。参见 skills/sdlc/sdlc-core/prepare-merge.md。保持框架的形式化体系与内容分离——内容应当存放于其独立的代码仓库中，本文档中的任何内容均仅用于演示说明。