weichen
4a7e19ad62
Why: a ContractRequest without a workspace (the conformance minimal case) resolved WorkDir to the process CWD and wrote .agentx transcripts into the repo, dirtying the tree in CI and failing the build step's worktree check. Evidence: GOWORK=off go vet + go test -count=1 ./... green; TestContractEmptyWorkspaceKeepsCWDClean pins the fixture bytes; the adapters/native tree no longer drifts after a suite run. Impact: requests with an explicit workspace are unchanged; empty workspace now lands in a disposable temp dir. Refs: Agent-System-Dev#242 CI failure (run 1144)
Agent-Native
独立的 Agent 执行基础仓库：自研执行内核（runtime）、模型与工具能力接入、外部 Agent 适配器（现有 PI Runner 等），以及共用执行契约与行为验收（conformance）。
本仓库是该模块的源码位置。Go 模块路径为 agent-native。
仓库分层
| 层 | 职责 | 依赖边界 |
|---|---|---|
| contract | 执行契约：Request/Result/Outcome/Error/Capability/Backend/Resolver | 不依赖内核、产品类型、数据库、配置，也不导入错误码库 |
| exec | 执行端口：Backend/Request/Result/ProcessEvent、预算、步骤重试与失败分类、交付物物化、Stub、并发限流 | 面向调用方的执行端口 |
| runtime | 多轮循环、工具调度、模型调用、执行会话 | 不导入 Core/Squad；可选使用日志库，nil 日志器不改变结果 |
| adapters | PI Runner transport / typed-result-v1；native：自研内核 runtime → exec.Backend（规范后端名 agent-native，含会话毒化轮转——resume-unsafe 失败后自动换新会话） | 显式映射外部差异，不伪造缺失能力 |
| conformance | 所有 Backend 共用的行为验收 | fake 验证契约，真实 adapter 验证能力 |
规范后端名：agent-native（pi-native 为兼容别名，由调用方注册表解析）。
包
| 包 | 内容 |
|---|---|
| contract | 四态执行契约 |
| conformance | 行为验收套件与 fake |
| exec | Backend/Request/Result/ProcessEvent（v0.2：Model/ToolAllowlist/Skills/Budget/SessionScope/ExecutionID/Env）、Budget、步骤重试与失败分类、交付物物化、Stub、并发限流 |
| runtime | 多轮循环（预算/取消贯穿、budget_exceeded 事件）、llm、session（compaction/元数据/崩溃安全）、tools（9 内置 + 策略层 Restrict） |
| runtime/mcp | MCP 客户端（stdio + Streamable HTTP）与 mcp____ 桥接（server 元数据不可信、上限收敛） |
| runtime/skills | SKILL.md 技能加载与 load_skill 渐进披露 |
| runtime/promptx | 系统提示结构化装配（环境事实 + 技能索引 + 交付物约束） |
| runtime/subagent | 委派端口（Request/Result/Factory）与 delegate_task 工具；嵌套执行由宿主注入 |
| adapters/native | runtime 作为 exec.Backend，含会话毒化轮转、compaction、技能/搜索/执行/MCP/委派装配（Options 显式注入，未配置不注册） |
| adapters/pitransport | typed-result-v1 编解码、远程结果解析、Runner 搜索、鉴权头（含 Node 摘要交叉验证测试） |
本模块不依赖 Core 或 Squad。上层产品依赖本模块的 contract 与 exec。
关键语义（详见 contract 包注释）
- ExecutionID 一次逻辑执行唯一；重试与受控 fallback 复用。
- Outcome 四态：Succeeded/Failed/Canceled/Unknown；Unknown 不静默降级。
- 失败副作用显式分类（none/possible）；possible 禁止无条件重放。
- 重试单一责任层：步骤级归调用方，传输级有界归 adapter，turn 上限归 runtime。
- Workspace 路径授权 ≠ OS 沙箱。
contract.ErrorCode取值是agent.*规范码。ErrorCode()/ErrorFields()供日志库识别，本包不导入错误码库。
依赖子模块
| 路径 | 作用 |
|---|---|
deps/development-guidelines |
开发规范，不参与编译 |
deps/error-code-system |
规范码目录。go.mod 的 replace 指向这里 |
deps/logging-system |
结构化日志。runtime 与 native 适配器可选使用 |
版本以本仓 gitlink 为准。scripts/submodule-consistency.sh 核对 gitlink 与检出的 HEAD。
git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git
# 已克隆时：git submodule update --init --recursive
CodeGraph
codegraph init 的索引写在 .codegraph/。仓库只跟踪 .codegraph/.gitignore。SQLite 数据库、WAL、pid、socket 和日志留在本机；根目录 .gitignore 与该文件双重忽略，避免索引被提交。
开发
在仓库根目录：
go vet ./...
go test ./...
依赖本仓库
消费方把本仓库当作独立模块。模块路径是短名 agent-native，在消费方 go.mod 中用 replace 指向检出目录：
require agent-native v0.0.0
replace agent-native => ./deps/agent-native
本仓自己的 go.mod 则把错误码库和日志库替换到 ./deps/。消费方若同时依赖这三仓，必须在消费方 go.mod 里写自己的 replace：依赖模块内部的 replace 不会在上层构建中生效。
远程：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git
CI
.gitea/workflows/ci.yml：go vet + go test（host runner）。