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

37 lines
4.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 工程索引与精确补丁契约 · 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](m2-index-tests-validation.json)。
界面验收包含独立浏览、长文件行定位、旧SHA、延迟项目请求、Python/导入依据、实际审查应用、390px及失败重试。真实模型使用四模块封存验收,源码增加420行受保护说明,其中两个模块有BOM/CRLF,要求仅定位正文并提交精确补丁;结果随[VALIDATION](VALIDATION.md)保存。完整多类工程、ChangeSet/worktree、引擎适配、桌面端/手机配对继续按产品计划开发。