从零开始接入 Cortex Agent,或将其集成到已有项目中。
如果机器已经通过 npm link、全局安装或 Volta 暴露了 cortex-agent,直接在目标项目根目录运行:
command -v cortex-agent
cortex-agent --version
cortex-agent init --lang zh如果项目已经存在 .agent/,使用纯加法升级:
cortex-agent update --lang zh给 LLM / AI 助手的初始化指令:
先执行 `command -v cortex-agent`。
如果命令存在,不要使用 npx,直接执行 `cortex-agent init --lang zh`。
如果当前项目已有 `.agent/`,执行 `cortex-agent update --lang zh`。
完成后运行 `/configure` 和 `/scan-project`。
保留当前项目自己的 Git user.name / user.email。
用户也可以只把 cortex-agent 的 GitHub 项目链接和目标项目路径交给 AI 助手。AI 助手按下面步骤安装本地命令并初始化目标项目:
AGENT_REPO="https://github.com/Kucell/cortex-agent.git"
TARGET_PROJECT="/path/to/your/project"
INSTALL_DIR="$HOME/.local/share/cortex-agent"
if ! command -v cortex-agent >/dev/null 2>&1; then
if [ -d "$INSTALL_DIR/.git" ]; then
git -C "$INSTALL_DIR" pull --ff-only
else
git clone --depth 1 "$AGENT_REPO" "$INSTALL_DIR"
fi
cd "$INSTALL_DIR"
npm link
fi
cd "$TARGET_PROJECT"
if [ -d ".agent" ]; then
cortex-agent update --lang zh
else
cortex-agent init --lang zh
fi适合直接发给 AI 助手的指令:
这是 cortex-agent GitHub 链接:<repo-url>。
这是目标项目路径:<project-path>。
如果本机没有 `cortex-agent` 命令,请 clone 该 GitHub 仓库到 `$HOME/.local/share/cortex-agent` 并执行 `npm link`。
然后进入目标项目;已有 `.agent/` 就执行 `cortex-agent update --lang zh`,否则执行 `cortex-agent init --lang zh`。
初始化后运行 `/configure` 与 `/scan-project`。
不要修改目标项目自己的 Git user.name / user.email。
# 初始化当前项目(默认中文模板)
npx cortex-agent init
# 指定语言模板
npx cortex-agent init --lang=en
# 初始化到全局目录 ~/.agent
npx cortex-agent init --global初始化完成后,.agent/ 目录会被填充核心文件,并根据检测到的 AI 工具自动生成对应的入口配置文件(.cursorrules、.clauderules 等)和符号链接。
.agent/ 是唯一维护源。若某些工具生成 .agents/skills/source-command-* 之类的兼容目录,它们只属于外部发现适配层,不应手工维护;cortex-agent init/untrack 会把 .agents 视为本地生成目录。
适配器只负责发现命令;识别到 <command> 后,任何任务动作之前必须加载 .agent/workflows/<command>.md。若该真源缺失,必须显式报告“适配器与真源不一致”并停止,不得回退到适配器副本。这条约束由 AGENTS.md 中的 ## Compatibility Adapter Bootstrap 受管块承担,并由 templates/{zh,en}/.agent/rules/core-principles.md 第 11 条加锁。cortex-agent update 会以 marker-based 语义合并方式把该块补齐或刷新;运行期诊断示例见 platform-integration.md。
从现在开始,cortex-agent init 不只是创建 .agent/ 模板,也会为项目建立稳定的 cortex.project.json Project Identity。默认仍然是简单的 embedded local 模式,但项目从第一天就是 remote-ready:
cortex-agent init
↓
stable ProjectIdentity
↓
governance = filesystem:.agent
↓
以后可迁移 / rebind,而不创建新项目身份
常用治理命令:
# 查看 Project Identity、Governance Binding 和本地解析状态
cortex-agent governance status
# 绑定已存在的治理存储
cortex-agent governance attach --kind filesystem --locator ../project-agent
# 显式切换 binding(要求 expected-current,防止并发覆盖)
cortex-agent governance rebind \
--expected-kind filesystem \
--expected-locator ../project-agent \
--kind git \
--locator ../project-agent.git \
--ref main
# 非 embedded binding 可 detach;不会删除治理数据
cortex-agent governance detach \
--expected-kind git \
--expected-locator ../project-agent.git \
--expected-ref mainEmbedded Local
product/.agent/
Detached Local
product/.agent -> ../project-agent
Git-backed / Remote-ready
cortex.project.json
governance.kind = git
governance.locator = <portable locator>
如果 embedded .agent 中已经有 Task / Mission / Decision / Waitpoint 等状态,Cortex 不允许只改 locator 跳到另一个 store;这类切换必须经过 migration / verify / freeze / flip / verify / archive 事务,避免出现双权威源。
新设备或 Cloud Agent attach 后,恢复流程不是“直接继续写代码”,而是:
resolve ProjectIdentity
→ resolve GovernanceStore
→ load durable governance
→ resolve ExecutionWorkspace
→ reconcile branch / revision / CR / CI
→ check Decision / Waitpoint / Lock
→ controlled resume
Reconciliation 的结果是:
READYBLOCKEDRECONCILIATION_REQUIREDDEGRADED
DEGRADED 允许在可选 provider capability 缺失时继续;BLOCKED 和 RECONCILIATION_REQUIRED 不会被自动 repair。
- GitHub:已完成 live end-to-end 验证。
- GitLab:Provider Adapter + capability conformance 已通过;不宣称 live-tested。
- Gitee:Provider Adapter + capability conformance 已通过;不宣称 live-tested。
- Generic Git:Git protocol / GovernanceStore conformance 已通过。
| 命令 | 说明 |
|---|---|
cortex-agent init |
初始化 .agent/,并创建/保留稳定 cortex.project.json Project Identity |
cortex-agent init --lang=en |
使用英文模板初始化 |
cortex-agent init --global |
初始化到 ~/.agent(全局共享配置) |
cortex-agent init --track |
初始化时同时纳入 Git 追踪(默认本地忽略) |
cortex-agent upgrade |
纯加法升级:补充 .agent/ 新增文件;若缺失则创建根目录 AGENTS.md / GEMINI.md;刷新符号链接,绝不覆盖已有内容 |
cortex-agent update |
安全完整更新:先执行加法升级,再同步未被本地修改的框架管理脚本;本地修改会保留并返回部分完成状态 |
cortex-agent track |
开启 Git 追踪:移除本地忽略,自动 git add .agent |
cortex-agent untrack |
关闭 Git 追踪:git rm --cached + 写入本地忽略,不删除文件 |
cortex-agent doctor |
健康检查:验证 .agent/AGENTS.md/GEMINI.md 识别与 Git 状态 |
cortex-agent help --json |
输出 Agent/自动化可读取的 CLI 命令、参数、Management writer 与安全边界契约 |
cortex-agent query <projection> --project <path> |
查询目标项目公开的 Management API projection,输出 JSON |
cortex-agent mcp serve --project <path> |
启动绑定单项目的只读 Management API MCP stdio server;writer tools 禁用 |
cortex-agent dev |
前台启动 Agent 协作 Dashboard;端口占用时自动选择后续可用端口 |
cortex-agent runs list |
通过 Management API 列出最近的 Run,输出 JSON |
cortex-agent runs show <run-id> |
从 Management API read model 查看指定 Run,输出 JSON |
cortex-agent queues list |
通过 Management API 列出 Queue,输出 JSON |
cortex-agent sessions list |
通过 Management API 列出 Session(包括查询时派生的 stale 状态),输出 JSON |
cortex-agent add <platform> |
添加平台集成(如 cline、roo、codex) |
cortex-agent remove <platform> |
移除平台集成 |
cortex-agent list |
列出当前已安装的平台集成 |
旧项目缺少 .agent/.script-manifest.json,或清单由旧版冷启动生成时,来源无法证明的脚本会保持原样并报告部分完成。先备份产品仓和治理仓,在副本核对脚本差异;只有确认可以替换后才使用 --force-scripts。这项保护不负责迁移历史 Decision / Waitpoint 记录。
query 成功时 stdout 使用稳定的 JSON envelope,包含 command、projection、project、filters、data、summary 和 warnings。失败时 stdout 返回结构化 error.code,stderr 仅用于诊断;参数或 projection 错误退出 2,项目或 Management API 不可用退出 3。
周报和审计可使用 cortex-agent query activity --project <path> --since <date-or-rfc3339> --until <date-or-rfc3339>。时间边界包含首尾;纯日期按本地自然日解释。只有记录内的结构化时间会进入筛选结果,未知或无效时间单独返回,文件 mtime 不参与推断。
Agent 不应依赖记忆猜测 CLI。先调用 cortex-agent help --json,跨项目查询再调用 cortex-agent help query --json --project <path> 获取目标项目真实 capability;.agent 内部 Management API 脚本只保留为实现、调试和旧版本降级入口。
在已初始化的项目根目录启动 Dashboard:
cortex-agent dev命令会输出实际访问地址,并在服务运行期间维护 owner-scoped Dashboard Session。默认参数如下:
cortex-agent dev --port 8787 --interval-ms 3000 --session-id local-dashboard--port指定起始端口;被占用时自动尝试后续可用端口。--interval-ms指定 Dashboard 数据刷新间隔。--session-id指定可追踪的 Session 标识。Ctrl+C停止前台服务,并触发 Session 生命周期收尾。
dev 只是便捷的本地运行入口,不是 Dashboard 或 Management API 的唯一入口。服务停止后仍可执行:
# 生成静态 Dashboard
node .agent/skills/agent-dashboard/scripts/generate.js
# 直接读取 Management API 数据
cortex-agent runs list
cortex-agent sessions listinit 命令会自动检测项目类型,引导进入对应流程:
cortex-agent init
↓
/configure ← 在 AI 助手中运行
填写:项目简介 · 技术栈 · 主力语言 · 架构原则
↓
✅ 接入完成
/configure 会自动填充:
.agent/rules/tech-stack.md— 技术栈规则.agent/rules/architecture-design.md— 架构原则.agent/plans/task-progress.md— 项目路线图- 将选择的语言规范规则(TypeScript / Python / Go / Java / Swift)追加到
tech-stack.md
如果项目存在特殊运行时、设备、桌面端、跨机器 UI 或领域业务验证,建议基于模板创建领域验证技能:
.agent/resources/templates/domain-validation-skill.md
.agent/skills/validate-<domain>/SKILL.md
AI 调试期间产生的截图、日志和临时 JSON 默认放入:
.agent/debug/screenshots/
.agent/debug/logs/
.agent/debug/temp/
检测到 .cursorrules、CLAUDE.md 等旧配置文件时自动进入迁移模式:
cortex-agent init ← 自动复制旧配置到 .agent/imported_rules/
↓
自动注册 CLAUDE.md 项目信息到 .agent/references/project-context-from-claude.md
↓
/migrate-rules ← 引导式逐文件合并旧规则到新体系
↓
/scan-project ← 扫描项目模块,生成 .agent/references/ 知识库
↓
/configure ← 补充项目背景和架构原则
↓
✅ 接入完成
旧 CLAUDE.md 会保留两份:
.agent/imported_rules/imported_from_CLAUDE.md.md:原文备份,便于人工核对.agent/references/project-context-from-claude.md:正式项目上下文,并写入.agent/context-index.json
因此旧文件中的技术栈、命令、架构约定会立即进入 Cortex Agent 的 references/context-budget 体系;后续仍可再拆分到更细的 reference 或 .agent/rules/tech-stack.md。
cortex-agent init
↓
/scan-project ← 扫描项目模块,生成 .agent/references/ 知识库
↓
/configure ← 填写技术栈和架构原则
↓
✅ 接入完成
早上 /briefing → 同步当前阶段、活跃任务、今日优先级
/start-task T-xxx → 开始任务(加载上下文,planner 制定计划)
编码实施...
下班 /ship T-xxx → 一键交付(代码审查 → commit → 标记完成)
/update-refs → 有结构变更时增量更新知识库(可选)
下一步:查看 工作流命令列表 了解全部可用命令。