sentinel-agentos 0.1.2 → 0.1.3

package/README.md

@@ -261,10 +261,12 @@ Total: 156 | Failures: 2 | High-Risk: 3
 ## 📦 安装 · Installation
 
 ```bash
-npm install @Sentinel AgentOS/core
+npm install sentinel-agentos
 ```
 
-⚠️ **npm 包尚未发布 · *not yet published***，当前从源码使用 · *use from source:*
+即可使用所有功能。
+
+如果从源码开发：
 
 ```bash
 git clone git@github.com:jishuanjimingtian/Sentinel AgentOS.git
@@ -278,7 +280,52 @@ npm run build   # 编译到 dist/
 
 ## 🚀 使用说明 · Usage
 
-### 基础用法 · Basic
+### 三种接入方式 · Three Integration Modes
+
+Sentinel AgentOS 支持三种接入方式，从轻到重按需选择。
+
+| 方式 | 适用场景 | 代码量 | 说明 |
+|------|---------|--------|------|
+| **CLI** | 快速测试 / CI/CD | 1 行命令 | 直接命令行检验工具调用 |
+| **SDK** | 嵌入 Agent 框架 | 5 行代码 | `import { AgentOS }` 在进程内调用 |
+| **HTTP API** | 跨语言 / 远程服务 | HTTP 请求 | 独立 HTTP 服务，任何语言都能调 |
+
+---
+
+### 方式一：CLI（命令行）
+
+```bash
+# 安装
+npm install -g sentinel-agentos
+
+# 校验参数
+sentinel-agentos validate exec command="rm -rf /"
+sentinel-agentos validate write_file path=src/main.ts content="console.log(1)"
+
+# 风险评分
+sentinel-agentos risk exec command="sudo reboot"
+sentinel-agentos risk exec command="npm test"
+
+# 查看审计日志
+sentinel-agentos audit --limit 10
+
+# 查看状态报告
+sentinel-agentos status
+
+# 启动 HTTP 服务
+sentinel-agentos server --port 3300 --token ***
+
+# 查看帮助
+sentinel-agentos help
+```
+
+**支持的命令**：`validate` / `risk` / `audit` / `stats` / `profile` / `status` / `server` / `memory` / `help`
+
+---
+
+### 方式二：SDK（代码嵌入）
+
+#### 2.1 基础用法 · Basic
 
 ```typescript
 import { AgentOS } from 'sentinel-agentos';
@@ -400,6 +447,163 @@ sandbox.validate('rm', { path: 'src/main.ts' });
 await sandbox.execute('exec', { command: 'npm test', cwd: process.cwd() });
 ```
 
+#### 2.2 中间件（一行接入） · Middleware (one-liner)
+
+```typescript
+import { wrapAgent } from 'sentinel-agentos';
+
+// 一行接入——包裹你的 Agent 工具调用
+const sentinel = wrapAgent({ workspaceRoot: process.cwd() });
+
+// 每次工具调用前后调用即可
+const { allowed, reason } = sentinel.preCheck('exec', { command: 'rm -rf /' });
+// → { allowed: false, reason: 'Risk 9.18 → DENY' }
+```
+
+#### 2.3 OpenClaw 插件
+
+如果你在用 OpenClaw Agent 框架，直接以插件形式集成：
+
+```typescript
+import { sentinelPlugin } from 'sentinel-agentos';
+
+// 注册为 OpenClaw 插件，自动 hook 所有工具调用
+const plugin = sentinelPlugin({
+  workspaceRoot: process.cwd(),
+  preRegisteredRules: true,
+});
+// → onBeforeTool → 校验 + 风险评分
+// → onAfterTool → 验证 + 审计
+```
+
+---
+
+### 方式三：HTTP API（远程调用，跨语言通用）
+
+Sentinel AgentOS 可启动为独立 HTTP 服务，任何语言（Python/Go/Rust/Java...）都能调用。
+
+#### 3.1 启动服务
+
+```bash
+# CLI 一行启动
+npx sentinel-agentos server --port 3300 --token ***
+
+# 或代码中启动
+import { createServer } from 'sentinel-agentos';
+createServer({ port: 3300, apiToken: '***' }).start();
+```
+
+启动后健康检查（免 token）：
+```bash
+curl http://localhost:3300/health
+# → {"ok":true,"uptime":12.3}
+```
+
+#### 3.2 鉴权
+
+除 `/health` 外所有端点需要 `Authorization: Bearer <token>` header。否则返回 `401`。
+
+#### 3.3 API 端点参考 · API Reference
+
+**基础端点：**
+
+| 端点 | 方法 | 鉴权 | 说明 |
+|------|:--:|:--:|------|
+| `/health` | GET | ❌ | 服务健康检查 |
+| `/pipeline/pre` | POST | ✅ | 执行前校验（Schema + Risk + Snapshot） |
+| `/pipeline/post` | POST | ✅ | 执行后验证（Verify + Audit + Feedback） |
+| `/pipeline/report` | GET | ✅ | 质量状态报告（文本） |
+| `/pipeline/profile` | GET | ✅ | 质量画像（JSON） |
+
+**Guard / Memory / Feedback / Audit 端点：**
+
+| 端点 | 方法 | 说明 |
+|------|:--:|------|
+| `/guard/schema` | POST | 注册 Schema 校验规则 |
+| `/memory/preference` | POST | 设置用户偏好 `{"key":"language","value":"zh-CN"}` |
+| `/memory/fact` | POST | 添加事实 `{"fact":"用户在上海"}` |
+| `/memory/context` | GET | 获取当前记忆上下文 |
+| `/feedback` | POST | 记录隐性反馈 `{"signal":"user_explicit_approval"}` |
+| `/audit` | GET | 查询审计日志（支持 `?limit=&sessionId=&toolName=&status=`） |
+
+**反馈信号类型：**
+
+| 信号 | 强度 | 说明 |
+|------|------|------|
+| `user_explicit_approval` | +0.6 | 用户明确说"做得好" |
+| `user_immediate_continue` | +0.3 | 用户立即继续对话 |
+| `user_used_result` | +0.7 | 用户使用了 Agent 的结果 |
+| `user_shared_output` | +0.8 | 用户分享了 Agent 输出 |
+| `user_modified_output` | -0.5 | 用户修改了 Agent 输出 |
+| `user_deleted_code` | -0.8 | 用户删除了 Agent 创建的代码 |
+| `user_interrupted` | -0.6 | 用户打断了 Agent |
+| `user_repeated_instruction` | -0.3 | 用户重复了相同指令 |
+
+#### 3.4 完整调用示例
+
+```bash
+# 1. Pre-exec — 校验 + 风险评分
+curl -s -H "Authorization: Bearer $TOKEN" \
+  -X POST http://localhost:3300/pipeline/pre \
+  -H 'Content-Type: application/json' \
+  -d '{"toolName":"exec","parameters":{"command":"npm test"}}'
+# → {"preExec":{"schemaCheck":{"pass":true},"riskScore":{"score":0.19,"action":"auto"}},"snapshot":{...}}
+
+# 2. Post-exec — 验证 + 审计
+# （传入 pre 返回的 snapshot）
+curl -s -H "Authorization: Bearer $TOKEN" \
+  -X POST http://localhost:3300/pipeline/post \
+  -H 'Content-Type: application/json' \
+  -d '{"toolName":"exec","toolParameters":{"command":"npm test"},"toolResult":"all passed","snapshot":{...},"startTime":1718123456000,"endTime":1718123457000,"retryCount":0,"wasSelfCorrected":false,"hadTimeout":false,"userAccepted":true,"userProvidedEdit":false,"resultWasUsed":true}'
+
+# 3. 查看报告
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3300/pipeline/report
+
+# 4. 查询审计
+curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:3300/audit?limit=10&toolName=exec"
+
+# 5. 记录反馈
+curl -s -H "Authorization: Bearer $TOKEN" \
+  -X POST http://localhost:3300/feedback \
+  -H 'Content-Type: application/json' \
+  -d '{"signal":"user_immediate_continue","sessionId":"session_1"}'
+```
+
+#### 3.5 跨语言（Python 示例）
+
+```python
+import requests
+
+BASE = "http://localhost:3300"
+HEADERS = {"Authorization": "Bearer ***"}
+
+# Pre-exec
+resp = requests.post(f"{BASE}/pipeline/pre", json={
+    "toolName": "exec", "parameters": {"command": "npm test"}
+}, headers=HEADERS)
+data = resp.json()
+print(f"Risk: {data['preExec']['riskScore']['score']} → {data['preExec']['riskScore']['action']}")
+
+# Post-exec (pass snapshot from pre)
+snapshot = data["snapshot"]
+resp2 = requests.post(f"{BASE}/pipeline/post", json={
+    "toolName": "exec",
+    "toolParameters": {"command": "npm test"},
+    "toolResult": "all passed",
+    "snapshot": snapshot,
+    "startTime": 1718123456000, "endTime": 1718123457000,
+    "retryCount": 0, "wasSelfCorrected": False,
+    "hadTimeout": False, "userAccepted": True,
+    "userProvidedEdit": False, "resultWasUsed": True
+}, headers=HEADERS)
+print(f"Verify: {resp2.json()['postExec']['verifyPassed']}")
+
+# Report
+print(requests.get(f"{BASE}/pipeline/report", headers=HEADERS).text)
+```
+
+---
+
 ### API 层 · SDK API
 
 ```typescript
@@ -562,10 +766,10 @@ v1.0 已完成 100% 设计文档覆盖率、99 个测试全通过、TypeScript
 </details>
 
 <details>
-<summary><b>Q: npm 包什么时候发布？ · When npm publish?</b></summary>
+<summary><b>Q: npm 包已经发布了吗？ · Is npm package published?</b></summary>
 
-TODO。当前可以直接 `git clone` + `npm link` 使用。
-*Currently use via `git clone` + `npm link`.*
+已发布。`npm install sentinel-agentos` 即可使用。当前版本 v0.1.x。
+*Published. Just `npm install sentinel-agentos`. Current version v0.1.x.*
 </details>
 
 <details>
@@ -600,7 +804,7 @@ const entries = api.auditQuery({ minScore: 3.0 }); // 高风险操作 · High-ri
 | v0.3 | Memory 层（3 层）· *Memory layer (3 layers)* | ✅ |
 | v0.4 | Evaluator 层（评估 + 反馈 + 画像）· *Evaluator* | ✅ |
 | v1.0 | 沙箱 + API + x- 扩展 + 校验补齐 · *Sandbox + API + x-ext* | ✅ |
-| v1.1 | npm 发布 · *npm publish* | 📋 |
+| v1.1 | npm 发布 + 三种接入方式 · *npm publish + 3 modes* | ✅ |
 | v2.0 | Docker 沙箱、Dashboard、SaaS · *Docker sandbox, Dashboard, SaaS* | 📋 |
 
 ---

package/dist/cli.js

@@ -59,7 +59,7 @@ Usage:
   sentinel-agentos stats
   sentinel-agentos profile
   sentinel-agentos status
-  sentinel-agentos server [--port N] [--token T]
+  sentinel-agentos server [--port N] [--token ***
   sentinel-agentos memory
   sentinel-agentos help
 
@@ -69,7 +69,7 @@ Examples:
   sentinel-agentos risk exec command="sudo reboot"
   sentinel-agentos audit --limit 10
   sentinel-agentos status
-  sentinel-agentos server --port 3300 --token my-secret
+  sentinel-agentos server --port 3300 --token ***
 `);
 }
 function fatal(msg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-agentos",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Sentinel AgentOS — 确定性 Guard 层 + 分层记忆 + 自动评估，让任何 Agent 变得可靠、可审计、可改进",
   "keywords": [
     "agent",