项目生命周期命令¶

这些命令用于检查项目、运行测试、生成构建产物、提交上架和启动 Agent。

命令	描述
`validate [target]`	校验项目或当前资源
`test`	进入测试管理
`build`	生成本地构建产物
`submit [options]`	生成并提交新版本
`run`	启动 Agent
资源管理入口	进入各类资源

test、build、submit、run 和资源入口在 project ▸ 下使用。validate 也可以在资源提示符下使用。

validate¶

validate 检查项目结构、必需文件、配置格式和资源引用。它只读取项目源码，不修改任何文件。

命令	描述	示例
`validate [target]`	校验当前范围；在 `project ▸` 可指定更小范围	`validate ability.guide_planning`

默认校验范围¶

省略 target 时，校验范围由当前提示符决定：

当前提示符	`validate` 校验什么
`project ▸`	整个项目
`Ability(<id>) ▸`	当前 Ability，以及它下面的全部 Node
`Node(<id>) ▸`	当前 Node
`Skill ▸`	全部 Skill
`Tool ▸`	全部本地 Tool 和 MCP Server
`MCP ▸`	全部 MCP Server
`Knowledge ▸`	全部 Knowledge
`Prompt ▸`	项目最外层 Manager Agent 的 Prompt
`Policy ▸`	Policy
`Config ▸`	Config
`Test ▸`	全部测试用例

集合资源还可以指定名称，例如在 Skill ▸ 输入 validate parse_intent，只校验这一项。Ability 和 Node 的校验对象由提示符确定，不接受额外名称。

在项目根指定目标¶

在 project ▸ 下，可以用 <target> 缩小校验范围：

目标	校验范围	格式说明
`config`	主配置	config.yaml
`policy`	权限策略	policy.yaml
`prompt`	项目最外层 Manager Agent 的 Prompt	Prompt 文件
`knowledge`	全部 Knowledge	retrieval.yaml
`knowledge.<name>`	指定 Knowledge	retrieval.yaml
`skill`	全部 Skill	SKILL.md
`skill.<name>`	指定 Skill	SKILL.md
`tool`	全部本地 Tool 和 MCP Server	tool.py、MCP 配置
`tool.<name>`	指定本地 Tool	tool.py
`ability`	全部 Ability，以及各自的 Node	ability.yaml
`ability.<ability_id>`	指定 Ability，以及它下面的 Node	ability.yaml
`test`	全部测试用例	测试用例

Node 只属于 Ability，因此不作为与 Ability 平级的项目 target。需要校验一个 Node 时，先进入所属 Ability，再进入该 Node，最后执行 validate。

Prompt 当前只有 prompts/system.md，因此只使用 prompt，不区分名称。MCP 属于 Tool，也没有独立的项目 target；validate tool 会一起校验 MCP。

目标支持 Tab 补全。目标不存在时不开始校验，而是显示可用目标。

校验输出¶

输出按“范围 → 文件 → 检查项”展开。每一项只有两种状态：

✅ successful
❎ error

完整项目校验示例：

project ▸ validate

project
  ✅ trismind/config.yaml
  ✅ trismind/policy.yaml

config
  ✅ required fields
  ✅ field types
  ✅ default ability reference

ability · guide_planning
  ✅ abilities/guide_planning/ability.yaml
  ✅ abilities/guide_planning/ability.md
  ❎ node references
     [unresolved_reference]
     abilities/guide_planning/ability.yaml:18
     node does not exist: review

  node · collect_info
    ✅ node.yaml
    ✅ prompt.md
    ✅ description.md
    ✅ resource references

summary
  checks      13
  successful  12
  error       1
  status      error

Ability 下的 Node 显示在该 Ability 内，不作为项目顶层资源单独列出。

没有使用某类可选资源时，不显示空分组，也不报错。例如项目没有 Skill，不会出现 skill error。只有配置中已经引用某个资源、但该资源不存在时，才显示 unresolved_reference。

全部通过时仍显示完整检查清单，末尾状态为：

summary
  checks      42
  successful  42
  error       0
  status      successful

什么情况会产生 error¶

错误类型	什么时候出现	如何定位
`missing_file`	必需文件不存在	显示缺失文件应在的路径
`missing_field`	必填字段缺失或为空	显示文件和字段路径
`invalid_type`	字段类型不符合定义	显示文件和字段路径
`invalid_value`	枚举、格式或取值范围不合法	显示文件和字段路径
`invalid_syntax`	YAML、Markdown、JSON 或 Python 无法解析	显示文件和行号
`invalid_path`	路径越出项目或指向不允许的位置	显示文件和字段路径
`duplicate_id`	同一范围中出现重复 id	显示冲突的两个位置
`unresolved_reference`	引用的 Ability、Node、Skill、Tool、MCP 或 Knowledge 不存在	显示声明引用的位置
`load_error`	Tool 无法导入，或 MCP 配置无法读取	显示对应文件

每份配置还会按自己的格式说明进行检查。例如 Config 的字段见 config.yaml，Node 的文件和字段见 node.yaml。第四章不重复列出配置字段。

只要出现一个 ❎，最终状态就是 error，并阻止 build。修改输出中指出的文件或字段后，重新执行相同的 validate。

test¶

test 进入 Test ▸，用于管理和运行项目测试用例。

输入位置	命令	描述	示例
`project ▸`	`test`	进入测试管理	`test`
`Test ▸`	`list`	列出全部用例	`list`
`Test ▸`	`new [name]`	新建用例	`new 东京路线`
`Test ▸`	`run`	运行全部用例	`run`
`Test ▸`	`run --case <id>`	运行指定用例	`run --case basic-travel-guide`
`Test ▸`	`delete <id>`	删除用例	`delete basic-travel-guide`
`Test ▸`	`exit`	回到 `project ▸`	`exit`

list 显示用例 id、名称、文件路径和最近一次运行结果。没有用例时显示 (none)。

new 省略名称时打开输入界面。名称会转换为小写 id，并生成 test/<id>.test.yaml；同名文件已存在时不覆盖。文件格式见测试用例。创建成功后停在 Test ▸，不会自动打开 IDE。

run 按 id 排序运行全部用例。每条结果显示用例 id、successful 或 error、耗时；失败时紧跟预期与实际结果的差异。全部通过时整体状态为 successful，任意一条失败时为 error。运行不修改用例或项目资源。

run --case <id> 只运行指定用例，id 支持 Tab 补全。目标不存在时不执行，并列出可用 id。没有用例时，run 提示先执行 new。

delete <id> 支持 Tab 补全。确认界面显示文件路径；确认后删除 YAML 文件，成功后停在 Test ▸。

build¶

build 校验当前源码，并生成可以检查或提交的本地产物。

命令	描述
`build`	校验并构建当前项目

build 不接受参数，也不要求先手动执行 validate。它按下面的顺序执行：

使用完整项目范围执行同一套校验。
任何检查项为 error 时停止，不生成或覆盖产物。
收集 Config、Policy、Ability、Ability 下的 Node、Skill、Tool、MCP、Knowledge、Prompt 和测试用例。
写出 manifest 和 package。

成功输出：

project ▸ build

validate  successful
resources 2 abilities · 5 nodes · 3 skills · 2 tools · 1 mcp
manifest  .trismind/builds/manifest.yaml
package   .trismind/builds/travel-guide-agent-0.1.0.zip
status    successful

manifest.yaml 记录项目元信息、当前项目版本、资源清单、文件摘要和构建时间。zip 是同一份 manifest 所描述的完整包。

构建产物写入 .trismind/builds/，默认不提交版本控制。再次构建同一版本时，只有新构建完全成功后才替换旧产物；失败时保留上一次成功构建。

build 不修改源文件，也不修改项目版本。需要改变版本时，先在 Config 中修改项目版本，再重新构建。

submit¶

submit 生成一个新版本并提交到智能体商店。

命令	描述	示例
`submit`	把 patch 版本加一后提交	`submit`
`submit --bump <patch\\|minor\\|major>`	按指定级别计算新版本	`submit --bump minor`
`submit --version <x.y.z>`	使用明确的新版本	`submit --version 0.2.0`
`submit --note "<text>"`	添加提交说明	`submit --note "修复行程生成"`

需要已登录并且网络可用。--bump 和 --version 不能同时使用；同时出现时命令直接拒绝。省略两者时等同 --bump patch，省略 --note 时使用 Update。

提交步骤¶

根据 Config 中的当前项目版本计算新版本，或使用 --version。
执行与 build 相同的完整校验。
用新版本生成 manifest 和 package。
执行提交前检查（preflight）。
上传 package。
远端接受后，更新 Config 中的项目版本，并保存本次成功产物。

以上步骤作为一次完整提交执行。校验、打包、提交前检查或上传任何一步失败，都不修改 Config，也不覆盖上一次成功构建。

提交前检查：

检查	什么时候为 error
登录与网络	未登录、离线或认证失效
版本	新版本不高于远端版本，或格式不合法
上架信息	名称、描述等必填内容缺失
权限	Policy 不完整，或资源使用了未声明的权限
敏感信息	package 中包含 token、密钥、凭据文件或项目外路径
包一致性	manifest、package 和目标版本不一致

成功输出会显示新版本、提交编号、审核状态，以及可以打开的详情链接：

project ▸ submit --bump minor --note "增加行程审核"

submit successful
project      travel-guide-agent
version      0.2.0
submission   sub_001
status       pending_review
package      .trismind/builds/travel-guide-agent-0.2.0.zip
review       https://agent-store.example/submissions/sub_001

字段	含义
`project`	提交的项目 id
`version`	本次生成并提交的版本
`submission`	本次提交的唯一编号；查询、撤回和反馈问题时使用
`status`	当前审核状态；提交成功后首先是 `pending_review`
`package`	本地保存的同版本 package
`review`	提交详情页；终端支持链接时可以直接点击

详情页显示提交说明、资源清单、权限声明、检查结果和审核进度。pending_review 表示版本已进入审核，尚未替换商店中正在发布的版本。

提交成功后，Config、manifest、package 和远端记录使用同一个版本。需要撤回待审核版本时打开 review 链接操作；删除本地 package 不会撤回远端提交。

run【待完善，勿看】¶

run 启动 Agent。会话选择、能力模式、Ultra 模式、运行命令和退出规则见运行命令。

资源管理入口¶

从 project ▸ 进入资源管理。

命令	描述
`ability`	选择或新建 Ability
`skill`	管理 Skill
`tool`	管理本地 Tool；从这里进入 MCP
`knowledge`	管理 Knowledge
`prompt`	查看和校验 Prompt
`policy`	查看和修改 Policy
`config`	查看和修改 Config

Node 只能从选定的 Ability 进入。MCP 只能从 Tool ▸ 进入。项目根不提供 node 或 mcp 入口。

完整示例：校验、测试、构建、发布【待完善，勿看】¶

project ▸ validate ability.general
✓ validation successful · checks 14  successful 14  error 0  status successful
  ✅ abilities/general/ability.yaml
  ✅ abilities/general/ability.md
  ✅ abilities/general/nodes/respond

project ▸ test
Test ▸ new smoke
✓ created test case smoke
  path test/smoke.test.yaml

Test ▸ run
✓ test run successful
  basic   successful   1ms
  smoke   successful   1ms
  cases 2  successful 2  error 0  status successful
  runtime prototype (deterministic adapter)

Test ▸ exit
project ▸ build
building · validating then packaging
✓ build successful
  validation   checks 27  successful 27  error 0  status successful
  resources    abilities 1 · nodes 1 · skills 0 · tools 0 · mcp 0 · knowledge 0 · tests 2
  manifest     /Users/alice/agents/my-travel/.trismind/builds/manifest.yaml
  package      /Users/alice/agents/my-travel/.trismind/builds/my-travel-0.1.0.zip
  version      0.1.0

project ▸ login
✓ successfully logged in as alice@example.com

project ▸ submit --bump minor --note "add smoke test"
submitting · validating, packaging, preflight, upload
✓ submitted for review
  project      my-travel
  version      0.2.0
  submission   sub_7f3a91c2
  status       pending_review
  manifest     .trismind/builds/manifest.yaml
  package      .trismind/builds/my-travel-0.2.0.zip
  review       https://store.trismind.local/projects/my-travel/submissions/sub_7f3a91c2
  note         add smoke test

提交失败时 Config 版本和上一次成功构建都保持不变：

project ▸ submit --bump minor --version 0.2.0
✗ --bump and --version are mutually exclusive