Files
Agent-Workbench/docs/CODE-INDEX-AND-PATCHES.md
2026-10-29 17:59:35 +08:00

4.6 KiB
Raw Permalink Blame History

工程索引与精确补丁契约 · 1.3.0

本切片将工程声明定位与局部编辑接入工作台已有的任务、审核、实际检查和Git交付。来源机制映射到C03/C04/C08;自有实现、契约检查与真实模型结果分别保存。

索引范围与依据

ProjectIndex为当前项目重新核对有界文件快照,并按每个文件SHA256复用或更新分析结果。导入目标候选每次重算,新增/删除文件也会改变结果。缓存最多8个项目,项目ID和真实根目录共同隔离;目前每次仍核对文件内容,没有后台文件监听或语义向量检索。

JS/TS/JSX/TSX/MTS/CTS采用MIT许可的@babel/parser 7.29.11,登记函数、类、方法、顶层变量、TS类型/接口/枚举与静态导出;导入、重导出、字面动态导入、字面require调用和TS import-equals来自语法节点。相对路径只比较当前范围的文件候选,包含JS→TS和MJS/CJS→MTS/CTS;有实际文件时优先该文件。候选附目标SHA256和runtimeResolution: not_verified,路径别名、调用绑定和动态参数仍需进一步分析。

Python采用移除注释/字符串体并识别缩进及声明的有界候选定位。结果明确显示python-declaration-candidate,保留行、名称、文件SHA256,使用前读取实际源码。没有执行Python代码,也没有进行Python编译器、完整引用或类型分析。

快照最多1000个候选文件/16MB;常规读取单文件最多1MB,声明分析最多256000字节,每文件300个符号/80000个AST节点,结果最多6000个符号与6000个导入。损坏文本、解析错误、读取/分析超限、无法确定静态目标的导入和不完整快照都显示范围。无匹配只表示当前查询范围;Go/Rust/Vue等暂保留文件指纹。

Git工程遵循ignore,常见依赖/生成目录、常见凭据、链接和子模块工作区排除。Git status可能运行配置的clean/process脚本,因此先只读取配置键名并在本次状态查询禁用这些脚本;未能确认配置时不声称基线完整。运行命令仍走原有独立确认流程。

使用与工件

  • index_project:摘要、覆盖范围、增量计数和有限示例;完整索引成为当前Task/Run的SHA256工件。
  • query_code:按名称/路径查找all/symbols/imports/files,查询最多200字,结果1–60条,附实际文件、行、SHA256和依据。
  • 项目只读API:GET /api/projects/:id/code-index、GET /api/projects/:id/code-query。单独浏览索引无需创建Task;模型执行保存任务工件。
  • 右侧「索引」可查找并打开原文件行。打开时重新读取文件;SHA256已变化时显示当前内容和刷新提示,清除旧行高亮。滚动限于代码容器,切换项目忽略旧请求返回。

精确编辑

propose_patch及POST /api/sessions/:id/patch-proposals要求现有文件路径、读取时64位SHA256、说明和1–32个old_text/new_text替换。非空锚点须在同一原文中恰好出现一次,全部范围不得重叠;输入顺序不会改变匹配基线。重叠、重复、未找到、过期SHA256、NUL和无效Unicode拒绝,空改动不产生提案。

统一LF/CRLF按原文件格式匹配与生成替换;混合换行按原文严格匹配。UTF-8 BOM单独保留。提案记录基线和结果SHA256、格式、替换数、原行范围及锚点/替换SHA256,保留未选中内容。新文件继续使用完整文本提案。

提案只保存到工作台,不写入工程;用户查看差异后应用。应用前再次核对实际文件基线,备份原字节并写入建议内容,冲突保留外部修改。精确补丁沿用逐文件状态,不提供多文件原子应用、改名/删除或worktree合并。长文件差异可定位首处实际改动,应用后的检查/提交仍由已有Task契约负责。

验证与剩余工作

源码检查覆盖实际AST行与导出、Python候选/多行签名、项目隔离、增量更新/删除与目标重算、MTS/CTS候选、过滤脚本不执行、损坏/大文件范围、BOM/CRLF/混合格式、唯一/重叠锚点、Unicode、冲突、Task工件/API与恢复。完整112项通过,见m2-index-tests-validation.json。

界面验收包含独立浏览、长文件行定位、旧SHA、延迟项目请求、Python/导入依据、实际审查应用、390px及失败重试。真实模型使用四模块封存验收,源码增加420行受保护说明,其中两个模块有BOM/CRLF,要求仅定位正文并提交精确补丁;结果随VALIDATION保存。完整多类工程、ChangeSet/worktree、引擎适配、桌面端/手机配对继续按产品计划开发。