principles-disciple 1.8.1 → 1.8.3

package/ADVANCED_CONFIG_ZH.md

@@ -0,0 +1,97 @@
+# 🛠️ Principles Disciple 高阶参数调优指南 (Geek Mode)
+
+> 💡 **给 99% 用户的建议**：您完全不需要阅读本文档。插件在默认配置下已经能在“保护代码安全”和“高效执行”之间取得最佳平衡。请直接享受 AI 编程吧！
+
+---
+
+如果您是那 1% 想要精细控制 AI 行为的极客，或者您发现 AI 最近太“怂”了总是拒绝干活，又或者觉得 AI 胆子太大经常改坏代码，那么欢迎来到**引擎核心区**。
+
+当您在一个目录下初始化了本插件后，系统会在该项目下生成一个隐藏配置文件：
+📂 `.state/pain_settings.json`
+
+修改这个文件，您可以直接改写 AI 的“性格”和“忍耐度”。
+
+## 📖 核心参数字典（说人话版）
+
+### 1. 痛点阈值 (`thresholds`)
+决定了 AI 遇到多大的挫折才会开始“反思”和“求助”。
+
+*   `pain_trigger` (默认: 30): **疼痛忍耐度**。当 AI 连续报错积攒的分数超过这个值，就会触发强制反思。调高它（比如 50），AI 就会变得更头铁，拼命尝试修复；调低它（比如 20），AI 一遇到困难就会停下来思考。
+*   `stuck_loops_trigger` (默认: 3): **死循环探测器**。如果 AI 连续修改同一个文件 3 次依然报错，系统判定它“卡死了”，会强制干预。
+
+### 2. 挫折评分 (`scores`)
+这些参数决定了 AI 犯错时“挨打”的力度。分数扣得越狠，AI 越容易进入“只读/保护模式”。
+
+*   `exit_code_penalty` (默认: 70): **报错惩罚**。只要跑代码报错了，瞬间增加这么多疼痛值。
+*   `tool_failure_friction` (默认: 30): **工具使用失败惩罚**。比如试图读取一个不存在的文件。
+*   `subagent_error_penalty` (默认: 80): **子系统崩溃惩罚**。这是非常严重的事故，分数很高。
+
+### 3. 时间与频率 (`intervals`)
+*   `worker_poll_ms` (默认: 900000 即 15分钟): **后台进化巡检间隔**。系统多久在后台扫描一次报错记录并总结出新规则。一般不需要改。
+*   `task_timeout_ms` (默认: 1800000 即 30分钟): **任务超时极限**。
+
+### 4. 信任与权限体系 (`trust`)
+这是系统的绝对核心。AI 初始有个“信任分”，干得好加分，瞎搞破坏减分。分数对应 4 个阶级（Observer -> Editor -> Developer -> Architect）。阶级越低，AI 受到的限制越多（比如不准写超过 10 行的代码）。
+
+*   **`stages` (阶级门槛)**:
+    *   `stage_1_observer` (默认: 30): 低于 30 分，AI 沦为纯“只读”模式，只能帮你查 Bug，不能改代码。
+    *   `stage_2_editor` (默认: 60): 能改小段代码，不能碰核心区。
+    *   `stage_3_developer` (默认: 80): 可以修改核心代码，但必须先写 `PLAN.md` 计划书。
+*   **`penalties` (扣分项)**:
+    *   `tool_failure_base` (默认: -8): 报错一次扣 8 分。
+    *   `risky_failure_base` (默认: -15): 在核心保护区报错，罪加一等，扣 15 分。
+*   **`rewards` (加分项)**:
+    *   `success_base` (默认: 1): 成功干完一个小任务，加 1 分。
+    *   `streak_bonus` (默认: 5): 连续 5 次成功（连杀奖励），额外加 5 分。
+
+### 5. 元认知深度反思 (`deep_reflection`)
+*   `enabled`: 是否允许 AI 停下来深思熟虑。
+*   `auto_trigger_conditions.error_rate_threshold` (默认: 0.3): 当近期操作的错误率超过 30% 时，强制让 AI 停下手头的活，调用 `deep_reflect` 工具分析自己是不是大方向搞错了。
+
+---
+
+### ⚠️ 高风险操作警告！
+
+如果您把 `penalties` 里的扣分调得极低（比如改成 -1），或者把初始信任分调得极高（100分），**防爆拦截系统实际上就失效了**。AI 将变成一个彻头彻尾的“莽夫”，这在操作大型复杂项目时极易引发灾难性的代码破坏。
+
+**修改建议**：推荐通过界面的 `auditLevel`（防爆拦截级别）来宏观调节，而不是直接魔改这些微观数值。
+
+---
+
+## ⚙️ 工作区目录配置
+
+系统通过以下方式确定工作区目录：
+
+### 配置文件（推荐）
+
+创建 `~/.openclaw/principles-disciple.json`：
+
+```json
+{
+  "workspace": "/home/user/my-workspace",
+  "state": "/home/user/my-workspace/.state",
+  "debug": false
+}
+```
+
+### 环境变量
+
+| 变量名 | 描述 | 示例 |
+|--------|------|------|
+| `PD_WORKSPACE_DIR` | 自定义工作区目录 | `/home/user/workspace` |
+| `PD_STATE_DIR` | 自定义状态目录 | `/home/user/workspace/.state` |
+| `DEBUG` | 启用调试日志 | `true` |
+
+### 优先级
+
+1. 环境变量 > 配置文件 > 默认值
+
+### 调试日志
+
+开启 `DEBUG=true` 后，日志会显示：
+
+```
+[PD:PathResolver] Using workspace from config file: /home/user/workspace
+[PD:WorkspaceContext] Normalized workspaceDir: /home/user/clawd/memory -> /home/user/clawd
+[PD:TrustEngine] Scorecard not found, creating initial scorecard
+```

package/AGENT_INSTALL.md

@@ -0,0 +1,173 @@
+# Principles Disciple - Agent Installation Guide
+
+> **给智能体的安装指引** - 请仔细阅读并按步骤执行
+
+---
+
+## 🚨 高危文件警告
+
+**以下文件包含用户积累的重要数据，绝不可删除或覆盖：**
+
+### 用户积累文件（最高优先级）
+
+| 文件 | 内容 | 风险 |
+|------|------|------|
+| `.principles/PRINCIPLES.md` | 用户积累的原则和教训 | 🔴 **删除 = 丢失所有经验** |
+| `.principles/PROFILE.json` | 用户配置和偏好 | 🔴 删除 = 重置所有设置 |
+| `AGENTS.md` | Agent 身份和记忆 | 🔴 删除 = 丢失身份认知 |
+| `SOUL.md` | Agent 核心人格 | 🔴 删除 = 丢失人格设定 |
+| `USER.md` | 用户偏好和上下文 | 🟡 删除 = 丢失用户偏好 |
+| `PLAN.md` | 当前工作计划 | 🟡 删除 = 丢失工作上下文 |
+| `MEMORY.md` | 长期记忆 | 🔴 删除 = 丢失长期记忆 |
+
+### 状态文件（不可删除）
+
+| 目录 | 内容 | 风险 |
+|------|------|------|
+| `.state/` | 运行状态、信任分、进化积分 | 🔴 删除 = 重置所有进度 |
+| `.state/evolution_points.json` | 进化积分记录 | 🔴 删除 = 积分归零 |
+| `.state/AGENT_SCORECARD.json` | 信任分数记录 | 🔴 删除 = 信任分重置 |
+
+### 可以安全更新/覆盖的文件
+
+| 文件 | 说明 |
+|------|------|
+| `BOOT.md` | 启动模板，可以更新 |
+| `HEARTBEAT.md` | 心跳模板，可以更新 |
+| `IDENTITY.md` | 身份模板，可以更新 |
+| `.principles/THINKING_OS.md` | 思维模型，更新后合并新模型 |
+| `.principles/models/*.md` | 思维模型库，可以添加新模型 |
+
+### 安全操作原则
+
+```
+1. 更新时：始终使用 smart 模式（默认），生成 .update 文件
+2. 删除前：确认文件不是用户积累文件
+3. 覆盖前：先备份原文件
+4. 合并时：保留用户的所有自定义内容
+```
+
+---
+
+## 快速判断：首次安装 vs 更新
+
+```
+检查 ~/clawd/.principles/PRINCIPLES.md 是否存在：
+├── 不存在 → 首次安装（跳到 [首次安装] 章节）
+└── 存在 → 更新（跳到 [更新] 章节）
+```
+
+---
+
+## 首次安装
+
+### 步骤 1：运行安装命令
+
+```bash
+npx create-principles-disciple --non-interactive --lang zh --workspace ~/clawd
+```
+
+### 步骤 2：重启 OpenClaw Gateway
+
+```bash
+openclaw gateway --force
+```
+
+### 步骤 3：验证安装
+
+```bash
+openclaw plugins list | grep -A 2 "Principles"
+```
+
+应该看到 `Principles` 显示为 `loaded`。
+
+### 步骤 4：初始化项目
+
+在项目目录下运行：
+
+```
+/init-strategy
+```
+
+---
+
+## 更新
+
+### ⚠️ 重要提醒
+
+**更新会生成 .update 文件，不会直接覆盖你的文件！**
+
+### 步骤 1：运行更新命令
+
+```bash
+npx create-principles-disciple --non-interactive --lang zh --workspace ~/clawd
+```
+
+### 步骤 2：查看更新内容
+
+```bash
+# 查看变更日志
+cat ~/clawd/docs/CHANGELOG.md | head -100
+
+# 列出所有 .update 文件
+find ~/clawd -name "*.update" -type f
+```
+
+### 步骤 3：合并更新
+
+**必须手动合并 .update 文件到原文件！**
+
+```
+对于每个 .update 文件：
+1. 读取原文件内容
+2. 读取 .update 文件内容
+3. 对比差异，将有价值的更新合并到原文件
+4. 删除 .update 文件
+```
+
+示例流程：
+```
+1. 发现 AGENTS.md.update
+2. diff AGENTS.md AGENTS.md.update
+3. 识别新增的章节或修改
+4. 将需要的更新合并到 AGENTS.md
+5. rm AGENTS.md.update
+```
+
+### 步骤 4：重启 OpenClaw Gateway
+
+```bash
+openclaw gateway --force
+```
+
+---
+
+## 常见问题
+
+### Q: 报错 "Cannot find module 'micromatch'"
+
+手动安装依赖：
+```bash
+cd ~/.openclaw/extensions/principles-disciple
+npm install micromatch@^4.0.8 @sinclair/typebox@^0.34.48
+```
+
+### Q: 如何查看当前版本？
+
+```bash
+cat ~/.openclaw/extensions/principles-disciple/package.json | grep version
+```
+
+### Q: 如何查看所有更新？
+
+```bash
+cat ~/clawd/docs/CHANGELOG.md
+```
+
+---
+
+## 版本信息
+
+当前文档版本：1.6.0
+
+更新此文档时，请同步更新版本号。

package/AGENT_INSTALL_EN.md

@@ -0,0 +1,173 @@
+# Principles Disciple - Agent Installation Guide
+
+> **Installation Guide for AI Agents** - Read carefully and follow the steps
+
+---
+
+## 🚨 High-Risk Files Warning
+
+**The following files contain user-accumulated data and must NEVER be deleted or overwritten:**
+
+### User Accumulated Files (Highest Priority)
+
+| File | Content | Risk |
+|------|---------|------|
+| `.principles/PRINCIPLES.md` | User's accumulated principles and lessons | 🔴 **Delete = Lose all experience** |
+| `.principles/PROFILE.json` | User configuration and preferences | 🔴 Delete = Reset all settings |
+| `AGENTS.md` | Agent identity and memory | 🔴 Delete = Lose identity cognition |
+| `SOUL.md` | Agent core personality | 🔴 Delete = Lose personality |
+| `USER.md` | User preferences and context | 🟡 Delete = Lose user preferences |
+| `PLAN.md` | Current work plan | 🟡 Delete = Lose work context |
+| `MEMORY.md` | Long-term memory | 🔴 Delete = Lose long-term memory |
+
+### State Files (Do Not Delete)
+
+| Directory | Content | Risk |
+|-----------|---------|------|
+| `.state/` | Runtime state, trust score, evolution points | 🔴 Delete = Reset all progress |
+| `.state/evolution_points.json` | Evolution points record | 🔴 Delete = Points reset to zero |
+| `.state/AGENT_SCORECARD.json` | Trust score record | 🔴 Delete = Trust score reset |
+
+### Files Safe to Update/Overwrite
+
+| File | Description |
+|------|-------------|
+| `BOOT.md` | Boot template, can be updated |
+| `HEARTBEAT.md` | Heartbeat template, can be updated |
+| `IDENTITY.md` | Identity template, can be updated |
+| `.principles/THINKING_OS.md` | Thinking models, merge new models after update |
+| `.principles/models/*.md` | Thinking model library, can add new models |
+
+### Safe Operation Principles
+
+```
+1. When updating: Always use smart mode (default), generates .update files
+2. Before deleting: Confirm file is not a user accumulated file
+3. Before overwriting: Backup original file first
+4. When merging: Preserve all user customizations
+```
+
+---
+
+## Quick Check: First Install vs Update
+
+```
+Check if ~/clawd/.principles/PRINCIPLES.md exists:
+├── Does not exist → First Install (skip to [First Install] section)
+└── Exists → Update (skip to [Update] section)
+```
+
+---
+
+## First Install
+
+### Step 1: Run Installation Command
+
+```bash
+npx create-principles-disciple --non-interactive --lang en --workspace ~/clawd
+```
+
+### Step 2: Restart OpenClaw Gateway
+
+```bash
+openclaw gateway --force
+```
+
+### Step 3: Verify Installation
+
+```bash
+openclaw plugins list | grep -A 2 "Principles"
+```
+
+You should see `Principles` showing as `loaded`.
+
+### Step 4: Initialize Project
+
+Run in your project directory:
+
+```
+/init-strategy
+```
+
+---
+
+## Update
+
+### ⚠️ Important Notice
+
+**Updates generate .update files, they will NOT directly overwrite your files!**
+
+### Step 1: Run Update Command
+
+```bash
+npx create-principles-disciple --non-interactive --lang en --workspace ~/clawd
+```
+
+### Step 2: Check Update Content
+
+```bash
+# View changelog
+cat ~/clawd/docs/CHANGELOG.md | head -100
+
+# List all .update files
+find ~/clawd -name "*.update" -type f
+```
+
+### Step 3: Merge Updates
+
+**You must manually merge .update files into original files!**
+
+```
+For each .update file:
+1. Read original file content
+2. Read .update file content
+3. Compare differences, merge valuable updates into original file
+4. Delete .update file
+```
+
+Example workflow:
+```
+1. Found AGENTS.md.update
+2. diff AGENTS.md AGENTS.md.update
+3. Identify new sections or modifications
+4. Merge needed updates into AGENTS.md
+5. rm AGENTS.md.update
+```
+
+### Step 4: Restart OpenClaw Gateway
+
+```bash
+openclaw gateway --force
+```
+
+---
+
+## FAQ
+
+### Q: Error "Cannot find module 'micromatch'"
+
+Install dependencies manually:
+```bash
+cd ~/.openclaw/extensions/principles-disciple
+npm install micromatch@^4.0.8 @sinclair/typebox@^0.34.48
+```
+
+### Q: How to check current version?
+
+```bash
+cat ~/.openclaw/extensions/principles-disciple/package.json | grep version
+```
+
+### Q: How to view all updates?
+
+```bash
+cat ~/clawd/docs/CHANGELOG.md
+```
+
+---
+
+## Version Info
+
+Current document version: 1.6.0
+
+Update this version number when updating this document.

package/INSTALL.md

@@ -0,0 +1,256 @@
+# Installation Guide
+
+## ⚠️ Known Issue: Plugin Dependencies
+
+### Problem
+
+When installing the plugin from source, you may encounter errors like:
+
+```bash
+Error: Cannot find module 'micromatch'
+Error: Cannot find module '@sinclair/typebox'
+```
+
+**Root Cause**: The plugin depends on external npm packages that are not automatically installed when using `openclaw plugins install` with a local path.
+
+---
+
+## ✅ Solution
+
+### Option 1: Automated Installation Script (Recommended)
+
+Run the provided installation script:
+
+```bash
+cd /path/to/principles
+./packages/openclaw-plugin/scripts/install.sh
+```
+
+This script will:
+1. ✅ Build the plugin
+2. ✅ Install all dependencies
+3. ✅ Copy files to the correct location
+4. ✅ Verify installation
+
+---
+
+### Option 2: Manual Installation
+
+If the script doesn't work, follow these steps:
+
+#### Step 1: Build the plugin
+
+```bash
+cd /path/to/principles/packages/openclaw-plugin
+npm install
+npm run build
+```
+
+#### Step 2: Install plugin dependencies
+
+```bash
+# Create the plugin directory
+mkdir -p ~/.openclaw/extensions/principles-disciple
+
+# Install dependencies in the plugin directory
+cd ~/.openclaw/extensions/principles-disciple
+npm install micromatch@^4.0.8 @sinclair/typebox@^0.34.48
+```
+
+#### Step 3: Copy plugin files
+
+```bash
+# Copy built files
+cp -r /path/to/principles/packages/openclaw-plugin/dist/* \
+    ~/.openclaw/extensions/principles-disciple/
+
+# Copy plugin metadata
+cp /path/to/principles/packages/openclaw-plugin/openclaw.plugin.json \
+    ~/.openclaw/extensions/principles-disciple/
+```
+
+#### Step 4: Verify installation
+
+```bash
+openclaw plugins list | grep -A 2 "Principles"
+```
+
+You should see:
+```
+│ Principles   │ principl │ loaded   │ ...
+```
+
+---
+
+### Option 3: Install from npm (Future)
+
+In future releases, the plugin will be published to npm:
+
+```bash
+npm install -g @openclaw/principles-disciple
+openclaw plugins install principles-disciple
+```
+
+This will automatically handle all dependencies.
+
+---
+
+## 📁 Workspace Configuration
+
+Principles Disciple needs to know where your agent's workspace directory is located. This is configured during installation.
+
+### Automatic Configuration
+
+The installer will automatically detect your OpenClaw workspace directory. You can also specify a custom directory:
+
+```bash
+# Run installer with custom workspace
+./install-openclaw.sh
+# Select "Custom directory" when prompted
+```
+
+### Manual Configuration
+
+If you skipped configuration during installation, you can set it up manually:
+
+#### Option 1: Configuration File (Recommended)
+
+Create `~/.openclaw/principles-disciple.json`:
+
+```json
+{
+  "workspace": "/path/to/your/workspace",
+  "state": "/path/to/your/workspace/.state",
+  "debug": false
+}
+```
+
+#### Option 2: Environment Variables
+
+```bash
+# Add to your shell profile (~/.bashrc, ~/.zshrc)
+export PD_WORKSPACE_DIR=/path/to/your/workspace
+export PD_STATE_DIR=/path/to/your/workspace/.state
+
+# Or set when starting OpenClaw
+PD_WORKSPACE_DIR=/path/to/your/workspace openclaw-gateway start
+```
+
+#### Option 3: Debug Mode
+
+To enable debug logging for path resolution:
+
+```bash
+export DEBUG=true
+```
+
+This will show detailed logs like:
+
+```
+[PD:PathResolver] Using workspace from config file: /home/user/workspace
+[PD:WorkspaceContext] Normalized workspaceDir: /home/user/clawd/memory -> /home/user/clawd
+```
+
+### Configuration Priority
+
+Configuration is resolved in this order (highest to lowest):
+
+1. Environment variables (`PD_WORKSPACE_DIR`, `PD_STATE_DIR`)
+2. Configuration file (`~/.openclaw/principles-disciple.json`)
+3. OpenClaw environment (`OPENCLAW_WORKSPACE`)
+4. Default (`~/.openclaw/workspace`)
+
+---
+
+## 🔍 Troubleshooting
+
+### Plugin fails to load
+
+**Error**: `Cannot find module 'micromatch'`
+
+**Solution**:
+```bash
+cd ~/.openclaw/extensions/principles-disciple
+npm install micromatch@^4.0.8
+```
+
+### Plugin version mismatch
+
+**Error**: Plugin shows old version
+
+**Solution**:
+```bash
+# Remove old version
+rm -rf ~/.openclaw/extensions/principles-disciple
+
+# Reinstall
+cd /path/to/principles
+./packages/openclaw-plugin/scripts/install.sh
+```
+
+### Configuration errors
+
+**Error**: `Invalid config: plugin not found: principles-disciple`
+
+**Solution**:
+```bash
+# Reset OpenClaw config
+openclaw doctor --fix
+
+# Reinstall plugin
+./packages/openclaw-plugin/scripts/install.sh
+```
+
+---
+
+## 📦 Dependencies
+
+The plugin requires the following npm packages:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `micromatch` | ^4.0.8 | Glob pattern matching for PLAN whitelist |
+| `@sinclair/typebox` | ^0.34.48 | Type definitions and validation |
+
+These are **not** included in the plugin bundle to keep the distribution size small. They must be installed separately in the plugin directory.
+
+---
+
+## 🚀 Quick Start
+
+After installation, enable the PLAN whitelist feature:
+
+1. Edit your workspace's `docs/PROFILE.json`:
+
+```json
+{
+  "progressive_gate": {
+    "enabled": true,
+    "plan_approvals": {
+      "enabled": true,
+      "max_lines_override": -1,
+      "allowed_patterns": ["docs/**", "skills/**"],
+      "allowed_operations": ["write", "edit"]
+    }
+  }
+}
+```
+
+2. Ensure `docs/PLAN.md` has `STATUS: READY`
+
+3. Restart your agent session
+
+Now even Stage 1 agents can edit files when a READY plan exists!
+
+---
+
+## 📞 Support
+
+If you encounter issues not covered here:
+
+1. Check the [GitHub Issues](https://github.com/csuzngjh/principles/issues)
+2. Create a new issue with:
+   - Error message
+   - OpenClaw version (`openclaw --version`)
+   - Plugin version (check in `openclaw plugins list`)
+   - Installation method used