Skip to content

Latest commit

 

History

History
337 lines (250 loc) · 12.8 KB

getting-started.md

File metadata and controls

337 lines (250 loc) · 12.8 KB

快速上手 (Getting Started)

从零开始接入 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。

GitHub 链接安装

用户也可以只把 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 临时使用

# 初始化当前项目(默认中文模板)
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。


Remote-ready 项目治理

从现在开始,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 main

三种常见模式

Embedded 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 事务,避免出现双权威源。

跨设备 / 跨 Session 恢复

新设备或 Cloud Agent attach 后,恢复流程不是“直接继续写代码”,而是:

resolve ProjectIdentity
→ resolve GovernanceStore
→ load durable governance
→ resolve ExecutionWorkspace
→ reconcile branch / revision / CR / CI
→ check Decision / Waitpoint / Lock
→ controlled resume

Reconciliation 的结果是:

  • READY
  • BLOCKED
  • RECONCILIATION_REQUIRED
  • DEGRADED

DEGRADED 允许在可选 provider capability 缺失时继续;BLOCKED 和 RECONCILIATION_REQUIRED 不会被自动 repair。

Provider 支持声明

  • 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 已通过。

CLI 命令参考

命令 说明
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 list

接入流程

init 命令会自动检测项目类型,引导进入对应流程:

场景 A:全新项目

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/

场景 B:已有项目(有旧 AI 配置)

检测到 .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。


场景 C:已有项目(无旧 AI 配置)

cortex-agent init
        ↓
/scan-project                 ← 扫描项目模块,生成 .agent/references/ 知识库
        ↓
/configure                    ← 填写技术栈和架构原则
        ↓
    ✅ 接入完成

接入完成后的日常节奏

早上  /briefing          → 同步当前阶段、活跃任务、今日优先级
      /start-task T-xxx  → 开始任务(加载上下文,planner 制定计划)
      编码实施...
下班  /ship T-xxx        → 一键交付(代码审查 → commit → 标记完成)
      /update-refs        → 有结构变更时增量更新知识库(可选)

下一步:查看 工作流命令列表 了解全部可用命令。