日常使用

CortexFS 的日常使用体验应当像 Unix 一样：先发现对象、读取状态，再在需要执行任务时运行文件或连接套接字。

查找可用对象

ctx ls model
ctx ls agent
ctx ls tool

常见对象形态：

/ctx/model/main
/ctx/model/debug/echo
/ctx/agent/executor
/ctx/agent/executor.sock
/ctx/tool/fs.read

命名文件用于执行工作，匹配的 .sock 处理有状态的 JSONL 交互，匹配的 .d/ 目录保存较小的控制文件。

在某些部署中，/ctx/agent/<name>.sock 是指向用户运行时套接字的所有者授权符号链接；在某些系统部署中它也可能是一个直接的套接字节点。两种形式都应当视为有效实现，按当前挂载暴露的形态使用 nc -U 或 readlink 探测。

直接调用模型

调试时先用回显模型：

/ctx/model/debug/echo "hello cortex"
echo "summarize this file" | /ctx/model/main

当你想更换默认模型时，修改 /ctx/model/main 的别名即可。请通过修改别名，而不是新增 provider 特定的根目录入口来完成。

参考树定义了 architect、executor、product-manager：

architect 是根规划与协调代理；executor 和 product-manager 以 agent:architect 为父项。executor 负责可写的实现与验证，product-manager 负责澄清用户价值和验收标准且默认只读。 agent/main 与 agent/main.sock 别名指向 executor。已退役的 base、coder、reviewer、worker 只是残留对象，不是受管树。

这三个角色是托管代理：bootstrap 写入 object-runner 包装脚本加上 system.md。打包的 Agent SDK 二进制 cortexfs-agent-architect、cortexfs-agent-executor、cortexfs-agent-product-manager 是可选可执行文件，会打印 role/mission/handoff 封装且不调用模型。它们是示例和可替换的 run 文件，不是默认的 /ctx/agent/<name> 包装脚本。见 One-file Extensions 与内部架构。

用以下命令启动并检查参考源：

ctx bootstrap
ctx bootstrap --check
ctx bootstrap --dry-run

ctx bootstrap 仅在以下任一项发生变化时才写入 bin/cortexfs.bootstrap.json：架构、树版本、受管代理列表或需要刷新的迁移条目。已淘汰的 base、coder、reviewer 与 worker 对象仍会被报告并保留，供人工复核，因为旧安装没有所有权清单和完整控制树完整性证明。一次成功的 bootstrap 会让下一次 --check 结果干净。

默认的 executor.d/system.md 将 executor 用于实现与验证。独立实现任务应写为 context/plan.json 中的委托 react 节点。省略 agent 时使用受管代理 executor；省略 session 时使用当前父会话名。父策略仍须允许 agent:executor create，默认选择不会授予权限。

显式填写的 agent 名称保持原有含义。旧计划中的 "agent": "worker" 仍需要对应对象和创建权限；迁移到全新安装时，请将这些计划更新为 "agent": "executor"。用如下命令推进计划：

ctx schedule status home/1000/agent/executor/session/default/context/plan.json --done plan
ctx schedule advance home/1000/agent/executor/session/default/context/plan.json --done plan
ctx schedule claim home/1000/agent/executor/session/default/context/plan.json work-123
ctx schedule result home/1000/agent/executor/session/default/context/plan.json work-123 done "implemented"
ctx agent wait executor work-123 --session default

status 读取计划、子节点表和委托 worker 的 agent/<name>、agent/<name>.d/model、life。当委托 backing agent 缺失时，它不会伪造 main/owned 默认值，随后打印 node<TAB>kind<TAB>agent<TAB>child<TAB>session<TAB>model<TAB>life<TAB>state。 advance 会材料化已就绪的子交接，claim 会将已材料化的子任务从 pending 变为 active，result 会把终态结果写入 context/child/<child>/。命令输出除了父引用外，还会携带子任务的 agent、session、model、life、handoff.md、result.md 和 refs.jsonl 的 ABI 路径，以免父节点或 worker 需要猜测协调状态。agent wait 是类似 waitpid 的非阻塞读取：当子任务处于 pending 或 active 时返回失败；当子任务进入 done、error 或 cancelled 时，打印 child<TAB>status<TAB>agent<TAB>session<TAB>model<TAB>life，随后打印 result.md。这些命令不会启动后台监听、轮询循环或第二套提交入口。

Provider 的密钥不会写入模型文件或 .d/ 控制目录。提供者适配器会优先从提供者环境变量候选项解析 API Key（若设置），其次读取 CortexFS 系统密钥存储 /var/lib/cortexfs/secrets/provider/<provider>/<slot>。若缺少所需凭据，模型状态为 unconfigured。

先为常见提供者安装文件化预设。list 会打印预设名、认证方式和目标文件：

ctx provider preset list
ctx provider preset show google
ctx provider preset install openrouter
ctx provider preset install deepseek
ctx provider preset install compatible --name local --base-url http://127.0.0.1:8317/v1 --model custom-model
ctx provider preset install openai
ctx provider preset install anthropic
ctx provider preset install google

规范提供者名仍是 openai、anthropic 与 google。gemini 是 google 的别名。聚合与地区 OpenAI 兼容预设会写入显式 name，使 /ctx/model/<provider> 保持稳定对象名。compatible 用于任意兼容端点，不是某个本地运行时的特殊分支。

模型代理不属于任何 agent，也不会写入 provider JSON。唯一的全局路由表是：

/ctx/model/route

该文件同时决定传输方式与密钥槽。多个提供者、多个模型与一个提供者的多个密钥都通过该表路由：

group(proxy) -> http(http://127.0.0.1:8080/v1), key(office)
group(local-socket) -> unix(/run/user/1000/cortexfs/proxy/openai.sock), key(local)

dip(198.51.100.45) -> direct
# dip(203.0.113.43) -> JP
domain(bestproxy.com) -> proxy
pname(NetworkManager, systemd-resolved, dnsmasq) -> must_direct
dip(geoip:private) -> direct
dip(geoip:cn) -> direct
domain(geosite:cn) -> direct
model(embedding-*) -> local-socket
fallback: proxy

key(office) 表示同一提供者的另一个凭据槽，并对应 /var/lib/cortexfs/secrets/provider/<provider>/office。若省略 key(...)，CortexFS 使用 default 槽。

管理代理

ctx agent 是当前 ABI 的轻量客户端。创建、启动与停止代理仍通过常规工具或文件 ABI 完成，它不会新增工作流入口：

ctx agent new reviewer --model openai/gpt-5.6 --tool fs.read
ctx agent new reviewer --label reviewer_t --shared project-a:read --mount /work /work ro
ctx agent new --from .cortexfs/agents/reviewer/agent.yaml
ctx agent apply reviewer --from reviewer
ctx agent start reviewer --session default
ctx agent status reviewer
ctx agent ps
ctx agent stop reviewer

主机侧的 agent.yaml（以及 agent.yml 和 agent.json）是编排输入。ctx agent new --from 与 ctx agent apply --from 会校验并将其实体化为 agent/<name>.d/*；运行时权限仍仅来自离散控制文件。--from NAME 会搜索 .cortexfs/agents 与 ~/.config/cortexfs/agents。

也可使用 Eve 项目作为同样的输入源，无需安装 Node 运行时：

ctx agent new --from ./my-eve-agent
ctx agent apply reviewer --from ./my-eve-agent

导入器只会读取 agent/instructions.md（静态）和 agent/agent.ts 中的字面量 model: "provider/model"。它会记录发现到的 Eve 工具、技能、频道、子代理与 schedule 并写入代理描述，但不会执行 TypeScript，不会暴露密钥，不会启动 HTTP 通道，也不会创建监听器。除非安装并通过策略允许相应的 CortexFS 工具，否则 Eve 能力仅作为源数据保留，确保在 Git/进程刷新边界处可复现。

schema: cortexfs.agent.profile/v1
name: reviewer
description: code review agent
instructions: Review diffs carefully.
model: openai/gpt-5.6
tools: [fs.read]
parent: agent:architect

ctx agent new 优先使用 /ctx/tool/agent.create；若该工具缺失，则由主机端 ctx 生成标准的 agent/<name>.d/* 控制文件和 home/<uid>/agent/<name>/ 骨架。ctx agent start 启动显式运行时；当终端套接字可达后，它会写入 agent/<name>.d/status=ready，并向 agent/<name>.d/log 追加 agent.start 事件。ctx agent stop 优先调用 /ctx/tool/agent.stop；若缺失则写入 agent/<name>.d/status=dead、清空 pid，并追加 agent.stop 事件。ctx agent status 与 ctx agent ps 仅读取普通的 agent/<name>.d/* 控制文件。agent status 先保留首行为状态值，再输出 model=...、life=...、parent=...、children=...、pid=...、uid=...、gid=...、groups=...、root=...、cwd=...。children=... 会统计状态不是 dead 的直接子项；ready 或 busy 且 pid 已过期的子项会被排除，规则与 ctx agent ps 一致。非默认模型与非 owned 生命周期会在 ctx agent ps 中可见。ctx agent env NAME 会打印由 ctx agent start 派生的沙箱环境，ctx agent children NAME 显示父视角的子任务状态，以及底层 worker 的 parent_session、model、life、status、pid。

AGFS 风格的服务组合通过现有文件 ABI 完成：使用 shared/<space>/data 存放持久值，使用文档化的 shared/<space>/queue/{inbox,pending,lease,claimed,done,failed} 重命名协议处理任务，并用受控的 fs.read、fs.list、fs.stat、fs.write 工具进行检查与变更。系统里不存在常驻插件 daemon、轮询 worker 或心跳命名空间；事实提交和普通 session/status 文件仍是事实源。

提交图片与其他文件

对于图片、PDF、音频、归档或其他二进制内容，请提交路径引用，不要把字节直接塞进提示词。CortexFS 保留文件本身在工作区或共享空间，并让代理可见；对话中只需描述任务和路径。

在当前目录启动代理时，该目录会默认挂载到 /workspace：

ctx agent start executor --session default
ctx send executor "Analyze /workspace/assets/screenshot.png and summarize UI issues"

需要更严格可见性时，使用显式挂载：

ctx agent start executor --session image-review \
  --no-default-workspace \
  --mount "$PWD/assets" /input ro \
  --mount "$PWD/docs" /docs ro \
  --cwd /docs

ctx send executor --session image-review "Inspect /input/screenshot.png and use /docs/DESIGN.md"

当多个代理或会话共享同一材料时，使用共享空间：

mkdir -p "$(ctx path shared project-a)/input"
cp screenshot.png "$(ctx path shared project-a)/input/"
ctx agent new reviewer --shared project-a:read
ctx send reviewer "Inspect /ctx/shared/project-a/input/screenshot.png"

这样可避免大文件进入消息历史。上下文只记录路径、摘要和引用；读取图片字节、提取文本、渲染缩略图或调用视觉模型应通过可见工具按需执行。

观察并连接终端

ctx agent start 默认会将调用者当前目录以读写方式挂载到沙箱内的 /workspace，随后从 /workspace 启动 ctxterm -> tsh。RW workspace 保留普通 Git 元数据可写；CortexFS 不再隐式把 .git 只读覆盖挂载。显式 path policy 仍可把 /workspace/.git 收窄为只读。代理的 HOME 是沙箱自身的 /home/agent，因此 shell 配置和缓存不会写入项目目录。托管外部 Agent CLI 时在 -- 后传精确 child：

ctx agent start executor --session default
ctx agent start executor --session default -- /usr/bin/codex
ctx agent watch executor --session default
ctx agent attach executor --session default

终端套接字位于：

/ctx/home/<uid>/agent/<agent>/session/<session>/terminal/main.sock

FUSE 可见路径统一指向 root 所有的 /run/cortexfs/terminal/broker.sock。ctx 会认证 broker，并请求指定的 Agent/会话；不会回退到旧用户级终端 socket。watch 是只读的；attach 会将你的标准输入连接到终端。

在需要时显式控制沙箱：

ctx agent start executor --session review \
  --no-default-workspace \
  --mount "$PWD" /workspace rw \
  --mount "$PWD/docs" /docs ro \
  --cwd /workspace

使用工具壳

tsh 是 CortexFS 的工具壳，不是宿主 shell。独立的人类会话中的 tsh 会按以下顺序解析：

CTX_HOME/.tshrc 中的 CTX_PATH=...
进程 CTX_PATH
默认 CTX_PATH=/ctx/tool:/ctx/home/<uid>/tool

在代理终端内，tsh 使用代理运行时基于策略、挂载和 uid/gid 推导出的进程 CTX_PATH。主机用户的 .tshrc 不会覆盖该授权路径。

.tshrc 是数据文件，不是 shell 语法：

CTX_PATH=/ctx/tool:/ctx/home/1000/tool

可用的检查命令：

tsh --list
tsh which fs.read
tsh help fs.read

直接调用工具时，优先在代理终端通过 tsh 发起，这样 CortexFS 可统一应用代理策略、挂载、uid/gid 与 CTX_PATH。

具有 agent.update 授权的代理可自迭代：工具会通过主机校验的运行能力套接字，原子替换调用代理自己的 system.md 或 prompt.template.md，新提示在下一次运行中生效。其他代理控制仍由主机所有，具体契约见 docs/spec/tool-policy-abi.md。

使用 agent.sh

仓库仍保留 agent.sh 作为 shell 前端：

install -m 0755 agent.sh/agent.sh ~/.local/bin/agent.sh
agent.sh --help
agent.sh executor
agent.sh executor "summarize this repository"
agent.sh --chat executor
agent.sh --attach executor
agent.sh --watch executor
agent.sh --session default executor "inspect the failing test"
agent.sh --resume executor

agent.sh executor 通过 ctx agent chat executor --session default 打开聊天界面；带入 prompt 参数时会转发一条消息到 ctx agent send executor --session default。使用 agent.sh --watch executor 观察代理终端，agent.sh --attach executor 仅在需要进入 ctxterm -> tsh 时使用。agent.sh 不会保有私有聊天数据库。

已安装环境中的多轮 smoke

安装后，应使用现有会话 ABI 做最小化多轮 smoke，而非新增测试入口：

ctx bootstrap
ctx agent start executor --session default --cwd /workspace
ctx agent send executor --session default "round one: read the current task"
ctx agent send executor --session default "round two: continue from the previous turn"
ctx agent history executor --session default
ctx agent output executor --session default

该路径会校验 agent/<agent>.sock、messages.jsonl、latest.md、会话选择与 prompt 历史注入。会话的持久事实保留在 /ctx/home/<uid>/agent/<agent>/session/<session>/messages.jsonl；ctx agent prompt 仅用于检查将要发送给模型的 prompt，不应替代实时套接字会话。

将独立实现工作交给 worker 时，父代理先用 ctx schedule advance 材料化交接，再提供子任务发出的 model=、life=、plan=、handoff=、result=、refs= 字段。worker 再通过同一条 ctx schedule claim/result 路径回写，不要新增队列、轮询器或第二套协调文件。

自定义代理

用户可编辑的系统提示位于：

/ctx/agent/<agent>.d/system.md
/ctx/agent/<agent>.d/prompt.template.md

示例：

ctx cat agent/executor.d/system.md
ctx set agent/executor.d/system.md "You are a careful Rust coding agent."
ctx cat agent/executor.d/prompt.template.md
ctx agent prompt executor

system.md 只定义人设与工作风格，prompt.template.md 定义这些内容如何与规则、技能元数据、工具注入、消息历史和运行时契约拼接，构成模型可见的第一条系统消息。模板变量包括 {{agent}}、{{current_time_unix}}、{{agent_instructions}}、{{rules}}、{{skills}}、{{tool_injection}}、{{history_messages}}、{{runtime_contract}}。

ctx agent prompt <agent> 会打印 CortexFS 当前可渲染的运行时系统提示，可用于检查模板、代理指令、可见 AGENTS.md 规则、受限技能元数据与运行时契约。真实模型调用时，工具注入和历史上下文仍由运行时按上下文窗口填充。

技能列表仅注入 name、description 与 SKILL.md 路径。完整 SKILL.md 内容仅在选择技能后再读取。技能元数据最多使用 2% 的上下文窗口；若窗口大小未知则硬上限为 8000 字符。超出配额时优先缩短描述，仍超出时会省略部分技能并在 prompt 中给出警告。

代理运行时会在该代理私有 session 目录中落一份“可用”快照（文本内容与 {{rules}} / {{skills}} 一致；快照写入不会阻塞运行）：

cat /ctx/home/$(id -u)/agent/executor/session/default/AGENTS.md
cat /ctx/home/$(id -u)/agent/executor/session/default/SKILLS.md

AGENTS.md：生效规则（全局 + 项目层合并）
SKILLS.md：仅技能元数据（name、description、path），不包含完整 SKILL.md 本体

这些 prompt 文件不授予任何权限。默认原生工具仍是 tsh；其他工具必须被发现、加载、Pin，并通过 tsh 调用。有效权限仍由 agent/<agent>.d/policy、path、mount、Linux uid/gid 与 mode bits 决定。

使用共享空间

共享空间是普通文件目录。用于项目素材、任务输入与各代理之间交换的结果：

ctx path shared project-a
cd "$(ctx path shared project-a)"

是否可读写共享目录由代理视图、挂载、策略、Linux uid/gid 与 mode bits 决定。

查看历史

ctx agent history executor
ctx agent output executor
ctx agent trajectory executor

不加 --session 时，命令首先读取 session/index/current，再回退到 default，因此查看当前最新会话不需要独立的 latest 子命令。

底层历史位于：

/ctx/home/<uid>/agent/<agent>/session/

历史是耐久事实；上下文是可重建工作集。上下文压缩不能破坏原始消息。ctx agent trajectory 会校验并打印所选会话 messages.jsonl 与 events.jsonl 的 ATIF 投影；工具调用、观测与用量仍按运行/调用 id 关联，命令不会创建第二套历史存储。

查找可用对象​

直接调用模型​

管理代理​

提交图片与其他文件​

观察并连接终端​

使用工具壳​

使用 agent.sh​

已安装环境中的多轮 smoke​

自定义代理​

使用共享空间​

查看历史​