Contributing and Development zh CN

贡献与开发指南

语言： English · 简体中文

LWC 欢迎边界清晰的缺陷修复、测试、文档、兼容更新，以及由真实 Agent 工作流证明必要的新能力。便利性优化必须以 canonical state 安全和机器可读契约不退化为前提。

开始之前

先搜索已有 issue 和当前源码。大范围行为变更、新外部集成、Store migration 或公共契约变化，应先提交 issue，让用户问题和验收边界得到讨论。

范围小、复现和预期结果都很明确的修复，可以直接提交 pull request。

任何贡献都不能依赖维护者私有 HOME、AMC 安装、plugin cache、binary 绝对路径或无官方文档的 Agent 格式。

仓库结构

路径	职责
src/	Rust CLI、Store、search、graph、Work、conversion、MCP、Viewer server 与 Agent integration
src/agent/targets/	每个受支持宿主对应一个手写 AgentTarget adapter
tests/	CLI、integration、packaging、release、safety 与 platform regression test
web/	只读 Viewer 源码与前端测试
web/dist/	随 Rust binary 嵌入并纳入版本管理的 Viewer build output
npm/	npm shim 与校验 GitHub Release binary 的安装器
.github/workflows/	CI 与跨平台 release gate
install.sh 与根目录测试辅助文件	安装和发布验证入口

编辑前先阅读路径最近的 AGENTS.md 和仓库原生说明。

本地环境

基础要求是当前 Rust toolchain、Git，以及 npm 和 Viewer 开发所需的 Node.js 22 或更高版本。

git clone https://github.com/JanYork/llm-wiki-cli.git
cd llm-wiki-cli
cargo build --locked
./target/debug/lwc --version

修改 Viewer 时：

cd web
npm ci
npm test
npm run typecheck
npm run build

MarkItDown、AnyDoc、图引擎、CodeGraph 和 Agent 宿主的可选验收应使用隔离环境。不要为了让无关单元测试通过，就把可选工具装进全局环境。

变更原则

• 修复共享根因。 修改某条症状前，先追踪公共函数的全部 caller。
• 保持 SQLite canonical。 Markdown、FTS、span、Work 产物与 graph sidecar 仍然属于派生或 deployment-local 状态。
• 保留 JSON 契约。 应增加 typed detail，而不是要求调用方解析 message。
• 明确部分成功。 Canonical commit 之后失败时，必须返回 recovery metadata 和幂等命令。
• 限制高密度工作。 分页、limit、cancel 和 query budget 都是产品行为。
• 保护外部文件。 Agent install、refresh、migration 与 uninstall 只能处理能够证明受管的内容。
• 使用官方集成证据。 MCP 是标准；宿主 config、Hook、Skill、Instructions、plugin 与 permission 格式并不统一。
• 选择最小但完整的改动。 不要为单一实现新建框架，也不要为没有真实需求的未来扩展增加配置开关。

测试驱动工作流

修改生产行为时：

1. 编写能够复现用户可见缺陷的最小 regression；
2. 运行并确认失败原因正是预期问题；
3. 在共享边界实现根因修复；
4. 重跑 focused test 和直接依赖方；
5. 使用隔离数据亲自执行真实 CLI 或 UI 路径；
6. 运行与改动面匹配的最终门禁。

如果测试失败是 fixture 自身写错，就不能算 red evidence。应先修正 fixture，再证明目标产品缺陷确实存在。

按改动面验证

改动面	最低本地证据
Rust 格式或代码	cargo fmt --all -- --check 加 focused test
Rust 公共行为	cargo clippy --locked --all-targets --all-features -- -D warnings 与相关 suite
Viewer	前端 unit test、typecheck、build 与真实 browser flow
npm installer	Node package test、隔离安装和 binary identity 校验
AgentTarget	global/local install、status、refresh 幂等、精确 uninstall、Hook 与 MCP 验收
Graph 或 Work	真实 queue/watch 终态、readback、适用的 cancel 或 recovery，以及 graph verify
Windows path 行为	Windows CI 或真实 Windows runner；不能用仅 macOS 的测试宣称覆盖
文档	双语语义审查、命令校验、Markdown lint 与内部链接检查

开发过程中只测试完整改动影响面和直接依赖方，不必每次文档编辑都重复昂贵且未受影响的 suite。最终 CI 与 release gate 仍覆盖完整支持矩阵。

安全测试

会修改状态的代码应覆盖：

• path containment 与 symlink ancestor；
• 并发 writer 与有界 busy 行为；
• canonical commit 前后分别失败；
• 幂等 retry 与 cleanup；
• draft/live、project/global 隔离；
• 删除或替换路径时的 Windows file-handle 行为；
• 外部 config 保留；
• secret 与 oversized input 拒绝。

不能靠 --allow-lint-issues、直接编辑 SQLite、任意 sleep，或在诊断前删除失败现场的 cleanup 让测试变绿。

文档贡献

英文是 canonical，每个核心页面都要有完整简体中文镜像，两种语言在同一 commit 更新。中文应符合技术语境，而不是把英文语序逐词替换成中文。

两种语言必须保留相同命令、JSON 字段、限制、警告与验收标准。只有页面双语版本和全部内部链接通过后，才能加入侧栏。具体规范参见 Wiki 编写规范。

GitHub Wiki 是独立的 Git 仓库，外部贡献者不能直接对它发 pull request。除非维护者授予直接 Wiki 写权限，否则应通过 issue 提交建议 Markdown 与证据。

Pull request 标准

Pull request 应说明：

• 用户可见问题及其影响；
• 选定范围与明确 non-goal；
• 复现或验收标准；
• focused test 与真实使用证据；
• compatibility、migration、security 与 performance 影响；
• 公共行为对应的文档更新；
• 不夸大的剩余平台限制。

Commit 应便于审查。不要把无关格式化、generated-file churn、dependency upgrade 与行为变更混在一起。

Review checklist

• 变更对应已证明的需求。
• Canonical 与 derived 边界仍然明确。
• Error 与部分成功契约保持机器可读。
• 改动面与直接依赖方有真实证据。
• 可选能力仍然以用户同意为前提。
• Agent 集成只依赖公开官方规范。
• 没有提交 secret、private path 或用户拥有的改动。
• 英文与中文文档语义一致。

完整维护者门禁与发布顺序见测试与发布流程。