nold-ai/specfact-cli-modules

# specfact-cli-modules SpecFact CLI 的中央模块注册表。此仓库托管官方的 **nold-ai** bundle 及其文档。 ## 命令概览 - [面向人类生成的模块命令概览](docs/reference/commands.generated.md) - [AI-agent 模块命令概览](llms.txt) ## 亮点：AI 形态的冗余检测 Code Review bundle 现在会显示 `ai_bloat` 发现结果：这是一种咨询性的、不影响评分的信号，专门针对 AI 辅助生成的代码中常见的冗余形态进行调优，例如标识性的 `try/except`、单次调用的包装器、直通的 lambda、多余的中间变量，以及过长的线性函数。针对此变更受影响包源码的试运行发现了 144 个咨询候选对象，并应用了 0 次自动重写；请使用 `specfact code review run --json --out .specfact/code-review.json`，然后在你的 AI IDE 中运行 `/specfact.08-simplify`，以便通过逐项确认来审查每一个简化建议。请参阅 [AI 冗余快速入门](./docs/quickstart-ai-bloat.md)。 ## 仓库结构 | 路径 | 用途 | |------|---------| | `packages/` | Bundle 源码包（每个 bundle 一个目录） | | `registry/` | 已发布的注册表索引和 tarballs | | `docs/` | Bundle 和模块文档（发布至 GitHub Pages） | | `scripts/` | CI 辅助脚本、签名脚本、质量门禁 | | `tests/` | 所有 bundle 的契约测试和单元测试 | | `openspec/` | OpenSpec 变更工件（提案、规格、任务） | 第三方 bundle 从各自的仓库发布，不在此处托管。 ## 首次设置 前置条件：Python 3.11+，[Hatch](https://hatch.pypa.io)。 ``` # 1. 创建共享的 Hatch 环境 hatch env create # 2. 将 specfact-cli 安装为可编辑依赖 # (优先使用 $SPECFACT_CLI_REPO，然后是匹配的 worktree 分支，最后是 ../specfact-cli) hatch run dev-deps # 3. 安装 pre-commit hooks（在每次 commit 时运行 quality gates 和代码审查） pre-commit install ``` 在 Cursor / VS Code 中，选择位于 `specfact-cli-modules/.venv/bin/python` 的解释器。 ## 质量门禁 在发起 PR 之前，请从仓库根目录运行完整的门禁流程： ``` hatch run format hatch run type-check hatch run lint hatch run yaml-lint hatch run check-bundle-imports hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump hatch run contract-test hatch run smart-test hatch run test hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json ``` pre-commit hooks 会在每次 `git commit` 时自动运行相同的流程（模块 1 和 2）。要针对所有文件手动运行它们： ``` pre-commit run --all-files ``` ### 门禁详情 - **格式化 / lint / 类型检查** — Ruff、basedpyright 和 pylint。`basedpyright` 和 `pylint` 的作用域限定为 `src/`、`tests/` 和 `tools/`；Ruff 则在整个仓库中运行。 - **check-bundle-imports** — 强制执行导入边界策略（`ALLOWED_IMPORTS.md`）。仅用于 `TYPE_CHECKING` 的导入不包含在检查范围内。 - **contract-test** — 契约优先的测试套件；必须在运行 `smart-test` / `test` 之前通过。 - **code review 门禁** — 对 `packages/`、`registry/`、`scripts/`、`tools/`、`tests/` 和 `openspec/changes/` 下暂存的 `.py`/`.pyi` 文件运行 `specfact code review run`。如果报告的 `ci_exit_code` 不为零，pre-commit hook 将阻止提交；警告和 `ai_bloat` 信息发现属于咨询性质，除非有记录在案的例外情况，否则必须在合并前予以修复。完整选项（`--mode`、`--focus`、`--bug-hunt` 等）详见 [Code review 模块](./docs/modules/code-review.md)。 ## 模块签名与版本控制 当你更改了 bundle 的源 payload 后，请提升 `packages//module-package.yaml` 中的 `version` 字段，然后刷新校验和： ``` python scripts/sign-modules.py --allow-unsigned --payload-from-filesystem packages//module-package.yaml ``` 在非 `main` 分支上，pre-commit hook 会自动运行此步骤，并重新暂存更新后的清单。 请针对每个 bundle payload 使用语义化版本控制：补丁用于修复 bug 和向后兼容的元数据或 schema 新增， 次要用于新增命令或公共 API 功能，主要用于破坏性的命令、API 或 schema 更改。 清单中的 `integrity.checksum` 值涵盖标准的模块源 payload；注册表中的 `checksum_sha256` 和 `.tar.gz.sha256` 文件涵盖已发布的 tarball artifact，因此这些哈希值可能会不同。 ### 何时需要签名 | 场景 | 要求 | |---------|------------| | 指向 `dev` 的 PR | 校验和 + 版本提升；无需加密签名 | | 指向 `main` 的 PR | 需要加密签名（`--require-signature`） | | 推送到 `dev` / `main` | CI 会在合并后通过 `sign-modules.yml` 自动签名 | | 已批准的同仓库 PR | `sign-modules-on-approval.yml` 会在合并前使用仓库密钥进行签名 | `registry/index.json` 和已发布的 tarballs **不会**在本地更新 —— 它们是由 `publish-modules` 在合并到 `dev`/`main` 后更新的。对于极少见的手动注册表修复，请使用 `hatch run sync-registry-from-package --bundle `（未接入 pre-commit）。 有关完整的签名工作流，请参阅 [模块签名](./docs/authoring/module-signing.md)。 ## 文档 - GitHub Pages: `https://nold-ai.github.io/specfact-cli-modules/` - URL 契约（核心 → 模块交接）：`docs/reference/documentation-url-contract.md`

标签：AI辅助开发, LNA, Python, 云安全监控, 代码审查, 无后门, 逆向工具, 静态分析