@onesclawkolor/onesclaw

v0.1.3

Published

a month ago

ONES internal AI Agent CLI

0High
0Medium
0Low

onesclawkolor

cli ai agent ones mcp

onesclaw

onesclaw 是一个面向 ONES 私有部署 / 运维场景的 AI CLI 助手。

它把 LLM、ONES MCP、Context7、本地 Markdown 知识库、Skills、Shell/SSH 工具、安全门禁和审计日志整合到一个命令行入口里，用来做：

ONES 运维文档问答
工单 / 任务状态查询
本地知识库检索
运维 helper scripts 生成与调用
受控 Shell / SSH 执行
阶段化 gate 验证与发布演练

当前状态

版本：0.1.3
公开 npm 包：@onesclawkolor/onesclaw
内部包名：@ones/onesclaw
当前阶段：PHASE-7.18
定位：内部运维 AI CLI / 智能助手原型，已达到试点发布态收口阶段

已落地的发布态能力：

公开 npm 安装与 tarball/curl 随机 URL 安装演练
doctor/auth/mcp/kb status -o json 统一状态输出
Linux/headless MCP 授权 URL 打印：onesclaw mcp login
Local KB / Context7 / ONES MCP 混合知识路由
Offline KB bundle：onesclaw kb pack/import
Scriptable Ops CLI：onesclaw ops envcheck/inspect/oinspect
Audit timeline：串联用户问题、知识源、MCP、shell/ssh 和最终回答

快速安装

公开 npm 安装

npm install -g @onesclawkolor/onesclaw
onesclaw --version
onesclaw init
onesclaw

私有 registry 安装

npm install -g @onesclawkolor/onesclaw
onesclaw --version
onesclaw init
onesclaw

curl 安装入口

curl | bash 不是当前默认推荐路径。上传后的入口 URL 记录在：

artifacts/install-entry-upload-report.json

使用方式：

curl -fsSL "<uploaded_url>" | bash

环境要求

Node.js >= 18
npm
macOS / Linux
Windows 请使用 WSL
本地 KB 需要已安装 qmd

检查：

node -v
npm -v
qmd --version

本地开发

npm install
npm run build
npm test
node dist/index.js

常用命令：

onesclaw doctor -o json       # 环境自检
onesclaw auth status -o json  # Provider 认证状态
onesclaw mcp status -o json   # MCP 配置状态
onesclaw kb status -o json    # 本地知识库状态
npm run dev                   # 开发模式
npm run build                 # 构建 dist/
npm test                      # 跑全量测试
npm run typecheck             # 只跑 TypeScript 类型检查
npm run doctor                # 本地环境自检
npm run gate:all:local        # 本地阶段门禁预检

本地知识库

ONES 运维文档问答优先使用本地 Markdown KB。

初始化：

onesclaw kb bootstrap --source /Users/kolor/Documents/guide

查看状态：

onesclaw kb status

检索：

onesclaw kb search --query "ONES是怎么部署的"
onesclaw kb search --query "ONES巡检怎么操作"

确定性运维命令：

onesclaw ops envcheck --preset medium --arch amd64 --dry-run
onesclaw ops inspect --baseurl http://127.0.0.1:30011 --dry-run
onesclaw ops oinspect --arch amd64 --dry-run

刷新：

onesclaw kb sync

导入离线 docs bundle（客户离线环境推荐）：

onesclaw kb import ones-guide-2026.05.tar.gz

标准 bundle 格式：

ones-guide-2026.05.tar.gz
  manifest.json
  content/**/*.md

kb import 成功后会自动切换到 knowledge.mode=offline，此时 ONES 文档问答不会 fallback 到 Context7。

知识库模式切换：

onesclaw kb mode
onesclaw kb mode hybrid
onesclaw kb mode offline

helper scripts 生成目录：

~/.onesclaw/kb/bin

当前典型脚本：

check.sh
download-package.sh
install-single.sh
install-ha.sh
backend-healthcheck.sh
oinspect.sh
reset-password.sh
gen-s3-config.sh

知识路由

onesclaw 不是纯 RAG。它会按问题类型选择数据源：

| 问题类型 | 默认路由 | 说明 | |---|---|---| | ONES 安装 / 部署 / 升级 / 巡检 / 环境检测 | Local KB | 命令型问题必须以本地 Markdown 命令为准 | | ONES 架构 / 支持哪些方式 / 概览解释 | Context7 优先，必要时 Local KB / Wiki fallback | 追求快答和简洁 | | 工单状态 / 负责人 / 项目缺陷 / 任务查询 | ONES MCP | 实时业务数据不能靠 RAG 回答 |

核心原则：

命令型 ONES 问答：Local KB 为最终命令来源
概览型 ONES 问答：hybrid 模式 Context7 优先，offline 模式 Local KB 优先
实时工单查询：ONES MCP
offline 模式：禁止 Context7 fallback

安全执行

Shell / SSH 高危命令有双保险：

confirmed=true + ask_user proof

也就是说，模型不能只带一个 confirmed=true 就执行高危命令，必须先经过用户确认并生成一次性 proof。

审计日志包含：

trace_id
session_id
turn_id
command_id
confirmed
proof_status
route_kind
primary_source

日志位置：

~/.onesclaw/logs/

常用审计命令：

onesclaw audit
onesclaw audit -o json
onesclaw audit -o csv
onesclaw audit --turn <turn_id>

审计时间线会聚合：

conversation.log：用户问题与最终答案
tool.log：Local KB / Context7 / ONES MCP 调用摘要
shell.log：本地 shell 执行摘要
ssh.log：SSH 执行摘要

项目目录

小白先看这些：

README.md          项目快速入口
AGENTS.md          AI agent 工作规则
docs/index.md      文档索引，进项目先看
src/               源码
tests/             测试
scripts/           gate、发布、自检脚本
docs/              需求、阶段、证据、review、总结

可以忽略的生成物：

node_modules/      npm 依赖，可重新 npm install
dist/              构建产物，可重新 npm run build
coverage/          覆盖率产物，可重新生成
*.tgz              npm pack 产物，可重新 npm pack
artifacts/         gate / release 报告，属于验收证据

详细目录说明：

docs/summaries/project-directory-guide.md

文档结构

所有项目 Markdown 文档统一放在 docs/ 下：

docs/
  index.md
  requirements/    需求变化
  task/            阶段任务与实现内容
  testcase/        测试用例与验收证据
  reviews/         Review 记录
  summaries/       总结、复盘、面试稿、部署文档

规则：

每个阶段必须有一个 PHASE-* 文件
每个阶段完成必须有一个 EVIDENCE-* 文件
每个阶段结束必须有一个 REVIEW-* 文件
阶段完成后必须有一个 SUMMARY-* 文件
需求变化必须进入 docs/requirements/REQ-CHANGE-*
AI agent 每次进项目先读 docs/index.md

常用验收命令

npm run build
npm test
npm run coverage:core
npm run doctor
npm run bench:knowledge
npm run gate:all:local

阶段 gate：

npm run gate:phase0
npm run gate:phase1
npm run gate:phase1_5
npm run gate:phase2
npm run gate:phase3
npm run gate:phase4
npm run gate:phase4-skills
npm run gate:phase5
npm run gate:phase6-provider

发布相关

公开 npm 发布：

npm run release:publish:public

私有 registry 发布：

npm run release:publish:private

安装入口上传：

npm run release:install:upload
npm run release:install:verify

发布前建议：

npm run build
npm test
npm run gate:all:local
npm run doctor

清理本地生成物

如果只是想让目录看起来干净：

rm -rf dist coverage node_modules
rm -f *.tgz .DS_Store

恢复：

npm install
npm run build

artifacts/ 是 gate / release 证据目录，通常保留；如果只是本地临时验证，也可以按需清理。

进一步阅读

AI 规则：AGENTS.md
文档入口：docs/index.md
当前阶段：docs/task/PHASE-7.2-offline-kb-import.md
目录说明：docs/summaries/project-directory-guide.md
标准部署：docs/summaries/standard-deployment-guide.md
面试讲述：docs/summaries/onesclaw-sre-interview.md