Code2KB Agent Toolkit 2.1.0｜问答用例维护

Code2KB Agent Toolkit 2.1.0 问答用例维护

发布日期 2026-11-10。

首次建库时，可以从核实过的事实设计问题。收到实际错答时，沿着原问法和证据分别核查知识正文、检索与回答，定位修复位置，再把确认过的问题留下复测。现有项目可直接使用该手顺。 问答用例维护

Kit 复用模块「问答自测」、候选验证包和检索问题集。项目方维护真实问题、业务判定及线上复测结果。已修复错答用于检查复发，未参与修复的真实问题用于测评整体回答质量。 公开受理与完成案例

预检与固定读取补充

• preflight 提前检查调用匹配状态、接口覆盖和双方锚点，并拒绝指向未登记模块的引用。实际跨模块目标和部署证据由正式流程核查。
• 在同一命令内复用入口集合及固定文件读取。公开 UniApp 夹具的清单在 check 中由读取 2 次降为 1 次，在 prepare --refresh 中由读取 3 次、解析 2 次降为各 1 次。
• 修正预检与正式流程的 Markdown 链接校验，覆盖尖括号链接及检索版的页内跳转。

安装与兼容

已有知识项目可继续使用现有文件，直接采用问答维护手顺。实际错答是否修复，由项目方在修正后的系统用原问法复跑。

git clone --branch v2.1.0 https://github.com/Ethereal-Space-one/code2kb-agent-toolkit.git
cd code2kb-agent-toolkit
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .
code2kb --version

兼容性说明

English

The QA case maintenance procedure covers initial authoring and feedback about incorrect answers. Review candidate knowledge, retrieved evidence and live answers separately, then add confirmed cases to the existing module QA checks. Use the original question for regression checks and reserve unseen real questions for quality measurement. Existing projects can adopt the procedure with their current files. English usage guide

The 2.1.0 supplement validates static call matching and reference ownership during preflight and reuses fixed Git reads within each command. The public UniApp fixture uses one manifest read and one parse in check and prepare --refresh.

Code2KB Agent Toolkit 2.0.0｜工具包更名与使用入口统一

Code2KB Agent Toolkit 2.0.0

把源码和这套工具交给 AI 编码助手，提取业务规则与实现依据，生成供机器人检索问答使用的知识文件。

本次变化

• 统一为 Agent Toolkit：产品、仓库与 Python 分发包更名，CLI 仍为 code2kb；新发布物的生成者为 Code2KB Agent Toolkit。
• 重写中英文首页与指南：说明输入、知识产物、适用用户、审核选择及操作手顺；配图同步更新。
• 包含此前主分支的全栈盘点、跨语言场景取证和可选英文知识输出补充；独立验证、检索与审核能力延续现有流程。

破坏性变更与旧项目

2.0 不提供旧名称兼容或自动迁移。新工具不审计、也不直接覆盖旧品牌发布快照；请保留原项目及其 Git 历史，使用生成时对应的工具审计。

已有知识可在新的知识 Git 项目中复用配置、知识源及所需审核材料，经检查后按正常审核与发布流程交付；不要复制旧发布目录或修改其清单身份。知识源格式、事实 ID 和文件协议保持不变，无须仅为品牌变化重写业务正文。

若同一环境装过旧包，先卸载 code2kb-spec，或使用全新虚拟环境。仓库提供源码安装入口，未上传 PyPI 包：

git clone --branch v2.0.0 https://github.com/Ethereal-Space-one/code2kb-agent-toolkit.git
cd code2kb-agent-toolkit
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .
code2kb --version

验证与边界

Python 3.9–3.13 CI 覆盖单元测试、规范与一致性夹具、检索结构、示例、安装、链接及公开内容检查。新包在源码目录外完成版本查询、发布与审计验证；旧品牌快照拒绝后内容不变，历史标签与冻结夹具保留原样。

使用者仍需提供 AI 编码助手、问答模型、FTS／向量索引和机器人部署。更名不会自动更新已有知识库或索引；静态源码取证不等于线上验证，结构检查不证明自然语言结论正确。详见使用指南和兼容性说明。

English

Code2KB Agent Toolkit turns pinned source evidence into business and engineering knowledge for retrieval-based Q&A. The repository and Python distribution are now code2kb-agent-toolkit; the CLI remains code2kb.

Breaking change: old-brand release snapshots must be audited with their original tool version. Reuse checked sources and required review materials in a new knowledge Git project; do not copy or relabel old release artifacts. No old-name compatibility or automatic migration is provided. The knowledge-source format is unchanged. Your agent, retrieval service and bot deployment remain external. See the English guide.

主分支补充：批次复核与只读预检（2026-11-09）

此补充进入 main，原 v2.0.0 标签和源码下载保持不变。需要下述能力时，请获取包含本次补充的主分支提交并重新安装；上面的标签安装示例对应原始 2.0.0。

• 新增 code2kb preflight：交稿前只读检查单模块候选结构和来源一致性，列出未检查项；不确认结论、不批准、不写发布清单。
• 批次统一取得真实影响队列；所有确认与准备完成后，以成功且明确零待复核的全局 check 收口，减少重复末次检查。
• 中英文手顺补充冻结后独审、续跑和原始材料引用。正式 prepare、审核授权和发布门禁不变。

本地 271 项测试通过；合成计时只代表重复校验阶段，不证明端到端建库提速。详见补充验收记录。

English: The main-branch 2.0 supplement adds read-only module preflight and a batch workflow that avoids redundant final impact checks. Formal preparation, review and release gates remain unchanged. The original v2.0.0 tag/archive is unchanged; use a main-branch commit containing the supplement. Synthetic timings cover only repeated final checks, not end-to-end production work.

Code2KB Spec 1.2.0｜独立验证者接口与校准

Code2KB Spec 1.2.0 增加可选的独立验证者：让「策略审核通过」不再只依赖作者自评，由与作者、审核执行者、策略授权人不同的另一方逐条核对结论，并用注入错误的校准题度量验证者的表现。

主要改动

• 新增可选策略结构版本 1.1（含 verifier_requirements）与外部报告信封 0.2：工具按当前候选和固定提交自行复算应查项，拒绝缺项、重复项，以及结论文字、源码片段或文件摘要与复算结果不一致的报告，并要求验证者独立于候选生产者、审核执行者和策略授权人。
• 新增两个只读命令 evidence-pack（生成只含固定提交源码片段与摘要的验证包）和 verifier-calibrate（用项目自己的事实生成含注入错误的校准题并评分）。
• 校准报告须提交 Git，并按注入错误数量、抓取率、误报率和有效期约束验证者；这些检查不证明结论为真，也不证明验证者在真实项目上不漏判。
• 策略 1.1 下，涉及权限、归属、金额、名额、指标或状态的规格结论设置风险下限 high 并要求启用 semantic_quality；执行者只能上调风险。
• 新增规范要求 C2KB-REVIEW-007 至 010（共 66 条）并补充保证范围矩阵；新增 .github/CODEOWNERS；无 fcntl 平台（Windows 原生）上修改类命令明确拒绝。

策略 1.0、信封 0.1、1.2 审核记录、双版发布物和文件协议 c2kb-file/1 均不变，现有知识项目无须迁移。完整变更见 CHANGELOG。

验证：本地全量测试 247 项通过；GitHub CI 的 Python 3.9–3.13 全部通过；规范编号 66 条、一致性夹具 66/66、最小项目、公开内容与发布边界检查通过。

后续补充 · 2026-11-04

全栈与跨语言取证补充已通过 PR #20 合并到 main，提交为 be50400。

• 增加语言无关的范围盘点与场景取证，按实际职责追踪客户端、服务、任务、数据与支撑依赖。
• 修复显式 --scope 下自有源码被祖先目录过滤的问题，保留嵌套过滤和安全限制；改进四类接口与方法关联错误的定位信息。
• 更新中英文 README 和操作示例，提供三个自行编写的公开跨语言知识发布与检索案例。案例保留条件和未知，不代表所有语言具备同等语义解析或线上问答保证。
• 本地 255 项测试通过；本次 PR 的 Python 3.9–3.13 必需 CI 全部通过；公开内容、链接、兼容与安装检查通过。

**获取方式：**使用包含上述补充提交的主分支代码，参阅当前 README。原 v1.2.0 标签和本页自动生成的源码归档仍为 2026-11-03 的原始发行快照，不包含本次补充；未移动标签或替换原始下载。工程版本仍为 1.2.0，文件协议仍为 c2kb-file/1。

后续补充：英文使用与知识输出 · 2026-11-04

英文使用与输出补充通过 PR #21 合并到 main，提交为 8dc792e。

• 人读的中英文指南与 AI 执行指引分别维护；单一 Skill 入口选择一份工作流，区分交互语言、知识正文语言和机器协议标识。
• 增加可选 content_language: en，绑定配置、正文、候选审核和冻结发布。正文与配置声明不一致时拒绝继续；翻译后须刷新候选并重新审核。
• 导航、检索单元和验证说明支持英文；补充条件、未知、风险下限和业务隔离的英文词面规则。固定文件名、内部表头和 ID 保留，部分终端诊断仍为中文。
• 英文声明检查一致性，不自动鉴别正文是否全为英文；实际写作语言仍需 AI 复核。公开案例使用预先编写的英文知识，验证发布、审计与实际 FTS5 召回，不代表真实模型写作或机器人最终回答已验证。
• 沿用已有本地验证记录；本次 PR 必需的 Python 3.9–3.13 CI 已通过，未追加本地测试或真实模型写作演练。

参阅英文使用指南和实施记录。本补充仍属 1.2.0；旧中文项目缺省不变，旧 CLI 可能拒绝新可选字段，使用英文能力请更新到包含补充的代码。

**获取方式：**使用当前 main 或上述合并提交。原 v1.2.0 标签及本页自动生成的源码归档仍指向原始发行快照，不含本次补充；没有移动标签或替换旧下载。

Code2KB Spec 1.1.0｜审核报告绑定与保证范围

Code2KB Spec 1.1.0 修复策略审核报告与发布候选之间的身份绑定，并明确规范能够实际保证的范围。

主要改动

• 新策略审核记录使用 1.2：外部报告信封绑定候选摘要、模块、检查、结果与带时区时间；报告文件仍须与 Git HEAD 和 SHA-256 一致。
• 旧 1.0/1.1 审核记录继续可用于历史核对，不可用于新策略批准。
• 发布 62 条规范要求的保证范围矩阵，区分机器检查、记录检查与人工流程；明确 CODE_VERIFIED 的锚点检查不证明自然语言结论正确。
• 补齐固定章节、表头、标识符、front matter 引号及 UTC 日期契约；CI 固定 Ubuntu 24.04，保留 Python 3.9–3.13 测试。

知识文件协议仍为 c2kb-file/1；本次不会改写已有知识项目或历史发布物。完整变更见 CHANGELOG。

验证：本地全量测试 226 项通过；GitHub CI 的 Python 3.9–3.13 全部通过，规范夹具 62/62、最小项目、公开内容与发布边界检查通过。

Code2KB Spec 1.0.0｜只读源码升级复核计划

Code2KB Spec 1.0.0 提供绑定固定源码提交与知识项目输入摘要的只读升级复核计划，帮助维护者确定源码变化后的复核范围。

• 区分需要重新解释业务语义的候选模块、全局基线触及和需要刷新审核的发布包；过期输入、未归属路径及未证实关系会保守拒绝或回退。
• 业务知识源及新发布物拒绝明确的源码仓库 URL；历史 0.8 发布继续按原规则和文件摘要审计。
• 保持知识文件协议 c2kb-file/1，继续支持旧 0.8.3 项目。
• 公开双模块与 PetClinic 五模块案例中，语义复核候选分别为 1/2、1/5，但基线迁移及审核范围仍为 2/2、5/5；当前不宣称节省净工时。

验证：217 项本地测试通过；Python 3.9–3.13 CI 通过；公开内容检查完成，独立代码审查指出的问题已修复。

边界：此版不自动改写知识、迁移证据、创建任务、批准、发布或接入机器人；静态源码证据不能证明线上运行结果或业务政策。

详细变更见 CHANGELOG.md。

Code2KB Spec 0.8.0｜检索完整性与源码升级预览

Code2KB Spec 0.8.0｜检索完整性与源码升级预览

0.8.0 改进从代码生成的知识在检索索引中的完整性，并帮助维护者定位固定源码升级后可能失效的知识。它仍以人工或预授权审核后的知识正文为发布来源。

• 可选检索单元继承文件前言，并在识别到约定的条件或未知标题时保留整篇正文；同模块的泛标题跨文件聚合。覆盖报告列出未入检索版的术语表，以及因限定关系不明而整篇保留、需复核的来源。
• preview-upgrade --all-modules 对比旧、新固定 Git 提交，报告路径与片段变化、可追踪的事实/主题/检索单元、候选重定位和未归属路径。结果只用于制定复核范围，不自动修改知识。
• 外部 FTS/向量索引的导入契约要求先写完并核对新快照，再切换指针。失败时旧快照仍可用；参考实现只提供内存模拟。
• 许可明确的 PetClinic 公开样本用受控第二提交演练一条查询分支变化，通过实际关系发布与全项目预览命令定位影响，并记录同一语料、问题和 top_k=1 下的 lexical-v1 与 SQLite FTS5 原始排名。该小样本不代表线上运行、最终模型回答或多语言检索质量。

工程版本从 0.7.0 升至 0.8.0；文件协议仍默认 c2kb-file/1，并继续兼容读取旧 0.8.3 项目。已有知识项目不必迁移或重新发布基础双版。若要使用新检索聚合规则，应从已审核知识生成新的检索扩展或新发布，按快照导入契约更新外部索引。已发布目录与清单不就地修改。

限制：工具无法从源码自动确认业务政策、线上行为或未建立的调用关系；全项目预览的候选与“未发现”结果不可当作事实已验证。

Code2KB Spec 0.7.0｜公开协议编号与多语言候选适配

本版继续以固定源码提交为证据，提取可复核的业务行为与代码逻辑，形成业务版、研发版及检索知识。

• 文件协议分离：新知识项目默认使用 c2kb-file/1。既有 0.8.3 项目可继续检查、准备、发布和审计，无需为工程升级迁移。需要换用新编号时，可先预演再显式执行；迁移只修改工作源配置，不自动批准或发布，也不改旧发布物。
• 多语言候选适配：增加统一 Adapter 契约、能力声明、通用 L1 文件级降级及 TypeScript/Java 保守候选。候选和同路径关系线索须经人工证据复核，不能直接视为业务事实或可信的跨仓库调用链。
• 公开样本回归：用 Spring PetClinic 固定源码检查候选、人工锚点映射、结构化事实、业务/研发双版发布审计与检索单元。样本不证明自动跨仓库配对、部署匹配或线上行为。

兼容细节见版本管理与升级说明。Python 3.9–3.13 的 CI 五项全部通过；本地完整单元测试 188/188 通过。

Code2KB Spec 0.6.0｜可恢复的本地知识库执行流程

Code2KB Spec 0.6.0 增加可选的本地接续执行器。现有知识项目无需启用运行账本，也无需重新发布。

新增

• 持久任务账本、批次检查点、允许写入范围检查和机器可读的 JSON 响应。
• 项目级修改锁、治理文件半写恢复，以及发布安装中断后的审计与恢复。
• Claude Code 与 Codex 共用的轻量 Host 任务适配；均使用同一任务契约。
• 已登记跨模块事实引用的影响复核；可选的发布阶段检索评测门禁。

验证

• 177 项单元与集成测试通过；公开源码接续样本 10/10 步通过。
• 合并提交 860ceb4 的 Python 3.9–3.13 CI 全部通过。

边界

运行账本及 Host 适配不授予批准；发布仍需既有授权。Codex 适配负责 CLI 任务渲染与接续，不自动配置工具权限。锁只协调同一台 Unix 主机上的受支持命令；文件差异检查不能代替目录权限隔离。

详见变更记录和使用与恢复说明。

Code2KB Spec 0.5.0｜关系与证据扩展

Code2KB Spec 0.5.0 增加可选的关系与证据扩展。不启用新扩展的项目保持原有双版发布流程，无需为此迁移知识文件。

新增能力

• 用稳定主题 ID 显式连接入口、接口、方法、事实与检索主题；候选和未解关系不会自动升级为已证实。
• 从固定 Git 提交重建源码片段，核对 blob 身份与片段摘要，并在切换提交前预览受影响事实和主题。
• 提供 UniApp/TypeScript 与 Java 的保守候选扫描，以及覆盖差异报告。
• 随发布冻结关系输入并生成独立清单；如同时发布检索版，绑定检索清单和单元。
• 从规范化事实生成业务、研发与检索结论段候选，不自动改写已审正文。

验证

• 合并提交 9739730 的 GitHub CI 在 Python 3.9–3.13 全部通过。
• 规范要求 61/61、既有一致性夹具 3/3、关系契约夹具 2/2；公开内容与 Markdown 链接检查通过。

使用边界

固定源码证据证明静态片段，不能证明运行结果或业务政策；候选关系不等于已证实事实。发布物离开源码仓库时，审计可核对冻结文件与摘要，不能重新取回源码证据。历史发布按对应 Git 快照恢复后审计。详见 关系与证据契约 与 兼容说明。

Code2KB Spec 0.4.0｜检索扩展

Code2KB Spec 0.4.0 增加可选的知识检索扩展。默认业务版与研发版发布流程保持兼容，现有项目无需为此迁移知识文件。

新增能力

• 从已审核的双版发布物生成按主题切分、按受众隔离的 Markdown 检索单元，绑定基础版本摘要。
• 提供路由索引、只读证据查询、离线评测、外部检索结果导入和检索扩展审计。
• 增加可选 compact 正文模式、full/compact 主题对照，并将 Agent Skill 分层加载。

验证

• GitHub CI 在 Python 3.9–3.13 全部通过；本地单元测试 132/132。
• 规范约束 61 条、一致性夹具 3/3；合成规模夹具 96/96。
• 独立公开的 Starlette 小型题集：开发集 3/3、保留集首次运行 3/3。

使用边界

检索层负责找到候选证据和未知边界，不判断最终答案是否可答。上述题集只验证固定问题的离线证据定位；生产检索总体质量、模型生成回答、机器人接入和线上权限均未验证。检索扩展需显式启用；未启用时保持原有双版发布行为。

详见 使用指南、检索契约 和 验收记录。