[yanfei0725]

这次只改一件事：把包从「压缩包 / 编译产物」变回可 review 的源码

上一版提交进来的 src/ptc/*.js 是 tsc 编译结果，外加 11 份手写 .d.ts。diff 里只能看到 exports.x = x 和 (0, mod.fn)()，reviewer 无法判断改了什么。这个 PR 把 13 个模块还原成 TypeScript 源，带原来的注释和类型。

目录

packages/ops-ptc/
├── src/ptc/            13 个 .ts（唯一实现源）+ agentbox.worker.cjs + schema.json
├── test/               12 个 .mjs 用例
├── scripts/build.mjs   tsc → dist，再拷两个非 TS 资源
├── tsconfig.json
├── vendor/README.md    说明 es.exe 由发布产物携带，不入库
├── bench/ docs/
└── package.json

没有 .tgz、没有 .tar.gz、没有 .exe、没有 dist/、没有 node_modules/。.gitignore 只拦这三类产物，src/ 下任何 .ts / .js 都不受影响。

构建变成真编译

build.mjs 原来是 cpSync(src, dist) —— 因为源就是产物。现在跑 tsc -p tsconfig.json，然后只拷两样不进 tsc 的东西：手写的 agentbox.worker.cjs（proc.ts 按 __dirname 直接拉起）和 schema.json（宿主当纯数据读）。

相对 import 去掉了 .js 后缀（'./engine-load.js' → './engine-load'），这样同一份源既能被 tsc 编译，也能被 node --experimental-strip-types 直接跑 —— 测试套件里有几支就是直引 src/ptc/*.ts 的。

单文件 1000 行

原 inproc.ts 1023 行，超了。按枚举接缝拆开：

文件	行数	内容
inproc.ts	884	AST 定位、改写、审计编排
enumerate.ts	269	walk / Everything 分级寻址、30s 缓存、子串预筛
inproc-error.ts	21	共享错误类

enumerate / clearEnumCache / EnumerateResult / LocateStrategy 仍从 ./inproc 导出，包对外 import 路径不变。当前最大文件 884 行，全部提交都在 1000 行以内。

验证

npm run build     tsc → dist（worker + schema 单独拷）
npm run verify    全绿

verify 展开后：22/22 pipeline regression、11 项 audit root cache、28 项 MCP 契约、safety / worker / protocol / mode-audit / locate-parity 各套件全过。导出面与旧 dist 逐模块比对一致（dist-shape 只对基线里存在的模块比对，新增的 engine-load / enumerate 不算导出变更）。

一个提醒

src/ptc/ 的手写 .d.ts 不在了 —— 声明文件现在由 tsc 的 declaration: true 生成，跟着类型走。如果维护者希望保留手工声明（比如为了压注释体积），那是另一个决定，这里按「源码即唯一真相」处理。

[OldLigant]

按 review 结论对这个 PR 做了一轮重整（提交 941a9e9，已直接推送到本 PR 分支），说明一下动机和取舍。

1. 文件整理

最初以压缩包形式提交、后来落到 packages/ops-ptc 独立包——这两种形态都撑不起工具注册，也不符合本仓库结构（原生能力都在 src/ 单包内）。现在整理为：

• 引擎源码 src/ast/（.cts 编译为 lib/ast/*.cjs），基准移至 bench/ast/，11 套测试改名 test/ast-*.test.mjs 随常规门禁运行
• 包导出 dsh-ops/ast、/ast/inproc、/ast/tools，ops-ast CLI 入口
• 双语文档 docs/ast-engine.md / ast-engine.zh.md

2. 工具重命名 ops_ptc_* → ops_ast_*

原名与现有 PTC 行（dsh-ops-ptc）撞名，"PTC 进程内 AST 改写"这类标题也名不副实。顺带修复一个硬伤：locate 的 body 参数用了 type: ['boolean','number']，而宿主 assertSupportedJsonSchema 直接拒绝 type 数组——已改为 exact-one oneOf，五个工具的 inputSchema 现已全部通过真实宿主校验器验证。

3. 披露方式：按渐进式披露设计（声明就绪，接线随后续 PR）

这五个工具是细分场景工具（大仓库符号级定位 / 结构化改写 / 语法审计），不是通用编辑：schema 大、使用频率低。若设为常驻，每轮请求都要在 tools 里带全五份声明，与本项目 token 效率的立身之本相悖；README 对 discovery 平台的定位（pdf / docx / 超多文件批量修改）恰好就是这类能力的归处。因此：

• tools.cts 保留 tools_addition 声明（load: 'on-demand'、能力关键词、minRepoFiles: 800）
• adapter.cts 的宿主 Outcome 信封（completed / partial / rejected + effectState / retry）是唯一模型侧接线点
• 引擎当前未注册进运行中的宿主，不给任何会话增加工具

4. 移除 MCP stdio 出口

跨 harness 的 AST / lint 类工具普遍以 MCP 形态存在是合理的：面向多客户端、协议通用、由服务器自管文件系统——本 PR 的原型也确实由此而来。但在 DSH 插件里这条路走不通：宿主权限模型（per-call sandboxPolicy、凭据防护、审计、取消）必须罩住每一次副作用，而独立 stdio 端点调用 handlers 时会全部绕过——原型文档自己也写了"使用 MCP 也不会自动继承原包的权限实现"。

这里有现成前例：dsh-ops 0.2.0 就是以 vendor FastCtx（一个 MCP 运行时）起家的，0.3.2 refactor! 把 FastCtx 连同 MCP 客户端一并移除，全面转向宿主原生的 per-call 策略。因此本次将 MCP server、其两个测试套件和 ./ast/mcp 导出全部删除；ops-ast CLI 保留为开发工具，模型可见的工具面只保留 createHostTools / registerHostTools + 可信桥这一条路。

5. 后续接线待办（把工具真正注册成渐进式披露）

• 实现可信 HostBridge：会话 sandboxPolicy 解析（read-only / workspace-write / full）、read-only 拒绝写模式（mutates）、AbortSignal 传递、凭据栅栏复核
• 经 registerHostTools 把五个定义挂进 discovery 行的 provider 模型：作用域所有权、presentation 判定、readiness 重校验，复用现有 ops_discover_tools 入口
• DISCOVERY_TERMS / allowedTools 增项：关键词复用 tools.cts 的 discover.keywords；确定默认池边界（locate / find / audit 只读可进，inproc / refactor 写路径按沙箱策略拒绝）
• dsh-plugin.json 声明（x-components 的 tools 清单）
• 文档同步：配置参考、组件参考、docs/工具发现.md
• 新增测试：read-only 拒写、跨作用域隔离与不继承、discovery 增量装配（新 agent 零重复探测）、宿主兼容冒烟回归

验证

node test/run.mjs ast- 11/11 通过，package-source 通过。本机全量门禁另有 42 个失败，均为预存环境问题（worker ACCESS_DENIED、linux-* 套件平台不匹配、时序抖动），与本改动无关，建议以 CI 为准。