mffdeo/devforge-ai-cli

# DevForge CLI [](https://github.com/mffdeo/devforge-ai-cli/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) DevForge CLI 是一个个人学习项目。它不是生产级的治理产品，不是合规工具，也不是通用的代码库扫描器。 该项目探索了一个问题： ## 这是什么 DevForge CLI 是一个实验性的命令行工具，用于围绕 AI 辅助开发工作流组织本地产出物（artifacts）： - 功能规格说明； - 项目概况与风险信号； - 实施简报； - 策略检查； - 人工审查记录； - 证据包； - pull request 指南。 它会在 `.devforge/` 目录下写入 Markdown 和 JSON 文件，以便可以在本地进行检查、版本控制和审查。 它**不会**调用内部 LLM。可选命令可以调用由用户配置的外部本地 agent，但这需要用户主动开启（opt-in）。 ## 为什么开发它 我想了解，在变更提交到 pull request 之前，围绕 AI 生成的代码需要多少结构化的工作。 最初的想法很简单：在合并 AI 辅助编写的代码之前，该工具会扫描代码库，对风险进行分类，制定计划，要求提供证据，并指导用户完成审查。 这个想法很有用，但实际的测试暴露了一个重要的局限性：确定性的启发式方法无法可靠地理解每一个项目。 ## 我想要的工作流 预期的工作流变成了： ``` init -> scan -> specify -> plan -> implement -> policy check -> review -> evidence -> pr-ready ``` 在实际操作中： ``` devforge init devforge scan devforge specify --idea "Add task priority" devforge plan --spec specs/SPEC-PRIORITY-001.md devforge implement --spec specs/SPEC-PRIORITY-001.md --agent codex devforge policy check --diff devforge review --issue SPEC-PRIORITY-001 devforge evidence --issue SPEC-PRIORITY-001 devforge pr-ready --issue SPEC-PRIORITY-001 ``` 重要的部分不是为了自动化而自动化。目标是让交接、假设、策略决策和证据变得明确。 ## 当前功能 DevForge CLI 目前包括： - `devforge init` 创建本地 `.devforge/` 治理文件夹； - `devforge scan` 收集确定性的项目信号并起草项目概况（Project Profile）； - `devforge profile approve` 明确批准项目概况； - `devforge specify` 根据功能创意生成可测试的 SPEC； - `devforge plan --spec` 生成计划包（Plan Pack）、上下文包（Context Pack）、策略决策（Policy Decision）、Agent 指令和实施简报； - `devforge implement` （可选）使用实施简报调用外部本地编码 agent； - `devforge policy check --diff` 根据本地规则评估当前的 diff； - `devforge review` 记录明确的人工审查； - `devforge evidence` 收集证据包（Evidence Pack）； - `devforge pr-ready` 准备 commit 和 PR 指南，但不会执行 commit 或 push。 这些命令都可以正常使用，但它们的输出应被视为可供审查的草稿，而不是最终决策。 ## 运行良好的部分 该项目作为一个工作流框架（harness）运行良好： - 它生成了有用的 Markdown 和 JSON 产出物。 - 它将隐式的交接明确化了。 - 它将实施与审查和证据分离开来。 - 它帮助阐明了 PR 应该包含哪些内容。 - 它创建了一个易于在本地检查的审计跟踪。 - 它让判断何时需要人工审查变得更容易。 最有用的部分是简报、证据包、审计跟踪和 PR 指南。 ## 运行不佳的部分 当被当作能够普遍理解项目的工具时，确定性的扫描器和计划生成器显得过于脆弱。 实际测试中出现了误报（假阳性）： - 一个简单的 Python CLI 计算器最初被判定为具有较高的风险； - 本地的 `input()` 很容易与个人数据混淆； - “session”或“sessão”这样的词可能会被误认为是身份验证； - 像“no database”或“sem banco”这样的短语，如果处理得过于简单，仍然可能触发数据库风险； - 通用项目词汇可能会使计划生成器倾向于特定的模板（例如身份验证）。 这些问题不仅仅是关键词错误。它们表明，对代码库的理解需要上下文、审查，并且可能需要 agent 辅助的推理。 ## 关键经验教训 1. 确定性的扫描应收集信号，而不是假装了解项目。 2. 项目概况应该由人工进行审查和批准。 3. DevForge 的最佳角色不是“通用扫描器”，而是“治理框架”。 4. AI 辅助开发需要的是结构化的交接，而不是又一个自主的 agent。 5. 策略决策必须与实际的项目和 SPEC 保持相称。 6. 输出应该是可供审查的草稿，而不是不容置疑的真理。 有关更详细的记录，请参阅 [LESSONS_LEARNED.md](LESSONS_LEARNED.md)。 ## 当前的局限性 - 扫描器是基于启发式规则的，且不完善。 - 策略引擎是实验性的，不是一个合规框架。 - 风险分类可能仍然会出错。 - 生成的 SPEC、计划和证据需要人工审查。 - 该项目不证明法律、安全、隐私或监管合规性。 - 无法保证该工具能理解您的架构。 - 外部 agent 执行是可选的，并依赖于用户在本地安装的工具。 - 一些实验性命令可能会在未来的版本中更改行为或被简化。 在没有经过您自己的审查、测试和控制的情况下，请勿将其用作生产批准系统。 ## 理想的未来架构 如果我继续将其作为一个严肃的系统来开发，我会将其分为三层： 1. **确定性信号** - 文件类型； - 框架提示； - 修改的文件； - 策略包； - 审计跟踪。 2. **Agent 辅助的推理** - 项目概况细化； - SPEC 澄清； - 风险分析； - 实施交接审查； - 证据完整性审查。 3. **人工确认的治理** - 批准的项目概况； - 批准的 SPEC； - 明确的审查； - 可追溯的策略决策； - 准备就绪的 PR 包。 CLI 应保持本地优先和透明。AI 应该帮助对上下文进行推理，但重要的决策应由用户批准。 ## 如何在本地尝试 该包未发布到 PyPI。请从 GitHub 安装或从源码运行。 使用 `pipx`： ``` pipx install git+https://github.com/mffdeo/devforge-ai-cli.git ``` 使用 `uv`： ``` uv tool install git+https://github.com/mffdeo/devforge-ai-cli.git ``` 对于本地开发： ``` git clone https://github.com/mffdeo/devforge-ai-cli.git cd devforge-ai-cli python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" pytest -v ruff check . ``` 尝试完整的实验流程： ``` devforge init devforge scan devforge profile approve devforge specify --idea "Describe your feature idea" devforge specify --spec specs/.md --approve devforge plan --spec specs/.md devforge implement --spec specs/.md --agent custom --command "echo" --dry-run The `echo` command is used here as a safe dry-run example. In a real experiment, replace it with your local coding agent command. devforge policy check --diff devforge review --issue devforge evidence --issue devforge pr-ready --issue ``` 在使用之前，请审查每一个生成的产出物。 ## 项目状态：实验性 / 学习项目 DevForge CLI 是一个实验项目。 它作为围绕 AI 辅助 SDLC 治理的实验记录很有用。它未被作为成品推销，也不应被视为一个完整的安全、合规或审查系统。 最有价值的成果是这一经验：**正确的形态是一个本地优先的 AI 治理框架，而不是一个声称能够理解所有项目的确定性工具。** ## 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。

标签：AI辅助编程, Homebrew安装, Python, 代码审查, 合规治理, 文档结构分析, 无后门, 软件开发, 逆向工具, 防御加固