Skip to content
One CLI

one status

用途

Section titled “用途”

one status 返回当前工作区的全量状态——workspace 元信息、子项目 列表、manifest 状态、infra 覆盖、issues、以及一个 ranked 的”下一步建议” 列表。它是 AI agent 在执行任何操作之前的”看世界”入口。

如果你是人类，one status（不带 --json）会输出彩色摘要；agent 用 --json（或在非 TTY 环境自动）拿到机器可读的结果。

用法

Section titled “用法”
Terminal window
one status [-d <dir>] [--json]

参数

Section titled “参数”
  • -d, --dir <dir>：工作区目录（默认 cwd）
  • --json：强制 JSON 输出

输出

Section titled “输出”

Schema：one-cli/status/v1

{
  "schema": "one-cli/status/v1",
  "workspace": {
    "root": "/abs/path/to/workspace",
    "is_one_project": true,
    "package_manager": "pnpm",
    "node_version": "20.17.0",
    "has_package_json": true
  },
  "subprojects": [
    {
      "name": "user-api",
      "relative_dir": "services/user-api",
      "template_id": "api-nest",
      "toolchain": "node",
      "package_manager": "pnpm",
      "scripts": ["build", "start", "test", "lint"],
      "manifest_tracked": true,
      "infra": {
        "dockerfile": true,
        "compose_service": true,
        "k8s_workload": false,
        "github_workflow": true
      }
    }
  ],
  "manifest": {
    "exists": true,
    "tracked_count": 1,
    "missing_in_manifest": [],
    "stale_entries": []
  },
  "infra": {
    "has_compose": true,
    "has_k8s": false
  },
  "summary": {
    "subproject_count": 1,
    "template_breakdown": { "api-nest": 1 },
    "toolchain_breakdown": { "node": 1 },
    "package_manager_breakdown": { "pnpm": 1 },
    "issue_count": 0
  },
  "coverage": {
    "dockerfile": { "enabled": true, "actual": 1, "expected": 1 },
    "docker_compose": { "enabled": true, "actual": 1, "expected": 1 },
    "k8s": { "enabled": false, "actual": 0, "expected": 0 },
    "github_workflow": { "enabled": true, "actual": 1, "expected": 1 }
  },
  "issues": [],
  "available_actions": [
    {
      "action": "add-more-subprojects",
      "command": "one add <template-id> --name <subproject-name>",
      "reason": "workspace is healthy; ready to add more subprojects",
      "priority": 10
    }
  ]
}

关键字段

Section titled “关键字段”

workspace.is_one_project

Section titled “workspace.is_one_project”

true 表示当前目录是一个 One workspace（one.manifest.json 文件存在）。 false 表示不是——agent 应该建议先执行 one create。

subprojects[].infra

Section titled “subprojects[].infra”

每个子项目的 4 个 infra 检查：是否有 Dockerfile、是否在 docker-compose 里有对应 service、是否在 k8s 里有对应 workload、是否有 GitHub Actions workflow。所有 4 个都为 true 表示该子项目的 infra 完整。

available_actions[] — AI Native 的核心

Section titled “available_actions[] — AI Native 的核心”

这是 status 作为 agent 入口的关键字段。它根据当前工作区状态 推断出ranked 的下一步建议：

[
  {
    "action": "create-workspace",
    "command": "one create <project-name>",
    "reason": "current directory is not a One workspace; create one first",
    "priority": 100
  },
  {
    "action": "fix-issues",
    "command": "one doctor --fix",
    "reason": "3 workspace issue(s) detected; auto-fix can resolve infra/manifest drift",
    "priority": 70
  },
  {
    "action": "add-subproject",
    "command": "one add <template-id> --name <subproject-name>",
    "reason": "workspace has no subprojects yet",
    "priority": 80
  }
]

priority 越高越紧急。Agent 通常应该按 priority 排序，挑第一个执行。

示例

Section titled “示例”
Terminal window
# 人类视角
one status


# Agent 视角
one status --json | jq '.available_actions[0].command'


# 验证某个子项目的 infra 是否完整
one status --json | jq '.subprojects[] | select(.name == "user-api") | .infra'


# 看 issue 数量
one status --json | jq '.issues | length'


# 跨工作区
one status -d /path/to/other/workspace --json

与 one doctor 的区别

Section titled “与 one doctor 的区别”
命令设计读者输出
one statusagent 优先严格 snake_case 字段 + summary / coverage / available_actions[]
one doctor人类 + CI健康检查；带 --fix 时执行修复

如果你写 skill 或者 agent 工具，优先用 status。CI gate 用 doctor --json；manifest 漂移统一用 doctor --fix 修复。