sgclaw: snapshot today's runtime and skill updates
This commit is contained in:
zyl
551
docs/plans/2026-03-26-zeroclaw-prompt-safety-hardening-plan.md
Normal file
551
docs/plans/2026-03-26-zeroclaw-prompt-safety-hardening-plan.md
Normal file
@@ -0,0 +1,551 @@
|
||||
# ZeroClaw Prompt Safety Hardening Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Harden ZeroClaw prompt handling and tool execution so non-skill freeform operations degrade to read-only or business-approved execution, while trusted skill-defined operations retain bounded execution privileges.
|
||||
|
||||
**Architecture:** Build a security gate around the existing prompt and tool-entry paths instead of rewriting the full prompt architecture. The gate classifies prompt-injection risk, records operation provenance (`trusted_skill` vs `non_skill`), sanitizes injected workspace/skill content, and enforces execution mode transitions (`clean`, `suspect_readonly`, `suspect_waiting_approval`, `suspect_business_approved`). Trusted skills gain structured business-operation metadata; non-skill operations require business-level approval before any privileged capability is released.
|
||||
|
||||
**Tech Stack:** Rust, vendored ZeroClaw (`third_party/zeroclaw`), existing approval/autonomy system, current prompt guard and prompt builder tests, `cargo test`.
|
||||
|
||||
### Task 1: Create an Isolated Worktree and Verify a Clean Baseline
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.gitignore`
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/**`
|
||||
|
||||
**Step 1: Verify the worktree directory is safe to use**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd /home/zyl/projects/sgClaw/claw
|
||||
ls -d .worktrees
|
||||
git check-ignore -v .worktrees
|
||||
```
|
||||
|
||||
Expected: `.worktrees` exists and is ignored by git.
|
||||
|
||||
**Step 2: Create the implementation worktree**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd /home/zyl/projects/sgClaw/claw
|
||||
git worktree add .worktrees/zeroclaw-prompt-safety-hardening -b zeroclaw-prompt-safety-hardening
|
||||
```
|
||||
|
||||
Expected: a new branch and worktree are created.
|
||||
|
||||
**Step 3: Build the baseline in the worktree**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening
|
||||
cargo test -p zeroclawlabs prompt_guard -- --nocapture
|
||||
cargo test -p zeroclawlabs build_system_prompt -- --nocapture
|
||||
```
|
||||
|
||||
Expected: existing relevant tests pass before any code changes.
|
||||
|
||||
**Step 4: Commit the clean worktree setup if `.gitignore` changed**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add .gitignore
|
||||
git commit -m "chore: prepare worktree for prompt safety hardening"
|
||||
```
|
||||
|
||||
Expected: commit only if `.gitignore` required an adjustment.
|
||||
|
||||
### Task 2: Add the Core Security-Mode Data Model
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/operation_policy.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/mod.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/operation_policy.rs`
|
||||
|
||||
**Step 1: Write the failing policy tests**
|
||||
|
||||
Add tests that prove:
|
||||
- suspicious non-skill input maps to `suspect_readonly`
|
||||
- trusted skill operations can request bounded privileged execution
|
||||
- any out-of-scope capability request downgrades the operation
|
||||
|
||||
Use concrete enums and assertions, for example:
|
||||
```rust
|
||||
assert_eq!(
|
||||
ExecutionMode::from_guard_and_provenance(GuardRisk::Suspicious, OperationProvenance::NonSkill),
|
||||
ExecutionMode::SuspectReadOnly
|
||||
);
|
||||
```
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening
|
||||
cargo test -p zeroclawlabs operation_policy -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because the new types do not exist yet.
|
||||
|
||||
**Step 3: Implement the minimal policy model**
|
||||
|
||||
Define:
|
||||
- `GuardRisk` (`Clean`, `Suspicious`, `Dangerous`)
|
||||
- `OperationProvenance` (`TrustedSkill`, `NonSkill`, `Mixed`)
|
||||
- `ExecutionMode` (`Clean`, `SuspectReadOnly`, `SuspectWaitingApproval`, `SuspectBusinessApproved`)
|
||||
- `CapabilityClass` for privileged business actions
|
||||
|
||||
Add small helper functions that do only state mapping. Do not pull prompt-building logic into this module.
|
||||
|
||||
**Step 4: Re-run the policy tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs operation_policy -- --nocapture
|
||||
```
|
||||
|
||||
Expected: the new policy tests pass.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/security/mod.rs third_party/zeroclaw/src/security/operation_policy.rs
|
||||
git commit -m "feat: add prompt security execution mode model"
|
||||
```
|
||||
|
||||
### Task 3: Add Structured Skill Trust Metadata
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/skills/mod.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/tools/read_skill.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/skills/mod.rs`
|
||||
|
||||
**Step 1: Write failing skill metadata tests**
|
||||
|
||||
Add tests that prove:
|
||||
- `SKILL.toml` can declare a business operation type, capability list, argument constraints, and `step_budget`
|
||||
- markdown-only skills default to unprivileged metadata
|
||||
- malformed privileged metadata is rejected or downgraded safely
|
||||
|
||||
Use a manifest shape like:
|
||||
```toml
|
||||
[skill]
|
||||
name = "export-report"
|
||||
description = "Export the monthly report"
|
||||
|
||||
[security]
|
||||
operation_type = "browser_export_data"
|
||||
allowed_capabilities = ["browser_read", "browser_export"]
|
||||
step_budget = 6
|
||||
approval_mode = "trusted_skill"
|
||||
```
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs skill -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because the structured metadata fields are missing.
|
||||
|
||||
**Step 3: Implement minimal structured metadata**
|
||||
|
||||
Extend `Skill` with a structured security block, for example:
|
||||
- `operation_type`
|
||||
- `business_description`
|
||||
- `allowed_capabilities`
|
||||
- `arg_constraints`
|
||||
- `step_budget`
|
||||
- `approval_mode`
|
||||
|
||||
Default markdown-only skills to unprivileged metadata so existing skills remain compatible.
|
||||
|
||||
**Step 4: Make `read_skill` expose the metadata**
|
||||
|
||||
Return or prepend enough structured metadata so the runtime can distinguish trusted skill operations from plain prompt text.
|
||||
|
||||
**Step 5: Re-run the tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs skill -- --nocapture
|
||||
```
|
||||
|
||||
Expected: skill parsing and `read_skill` tests pass.
|
||||
|
||||
**Step 6: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/skills/mod.rs third_party/zeroclaw/src/tools/read_skill.rs
|
||||
git commit -m "feat: add trusted skill security metadata"
|
||||
```
|
||||
|
||||
### Task 4: Sanitize Injected Workspace and Skill Content Before Prompt Assembly
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/prompt_sanitizer.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/mod.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/channels/mod.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/prompt.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/channels/mod.rs`
|
||||
|
||||
**Step 1: Write failing sanitizer tests**
|
||||
|
||||
Add tests that prove:
|
||||
- dangerous bootstrap phrases are removed, escaped, or summarized before prompt injection
|
||||
- control characters are stripped
|
||||
- overlong files are truncated with an audit-friendly marker
|
||||
- safe business content remains readable
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs build_system_prompt -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because injected files are still copied verbatim.
|
||||
|
||||
**Step 3: Implement the sanitizer**
|
||||
|
||||
Create a small sanitizer that:
|
||||
- strips control characters
|
||||
- caps content length
|
||||
- flags prompt-override phrases
|
||||
- emits sanitized content plus metadata such as `truncated` and matched rules
|
||||
|
||||
Use this sanitizer in:
|
||||
- `load_openclaw_bootstrap_files`
|
||||
- any shared path in `agent/prompt.rs` that renders workspace or skill text into the system prompt
|
||||
|
||||
**Step 4: Re-run the tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs build_system_prompt -- --nocapture
|
||||
```
|
||||
|
||||
Expected: prompt-building tests pass with the new sanitized behavior.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/security/mod.rs third_party/zeroclaw/src/security/prompt_sanitizer.rs third_party/zeroclaw/src/channels/mod.rs third_party/zeroclaw/src/agent/prompt.rs
|
||||
git commit -m "feat: sanitize injected workspace prompt content"
|
||||
```
|
||||
|
||||
### Task 5: Wire `PromptGuard` into Main Agent and Gateway Entry Points
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/prompt_guard.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/agent.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/gateway/mod.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/gateway/ws.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/agent.rs`
|
||||
|
||||
**Step 1: Write failing entry-point tests**
|
||||
|
||||
Add tests that prove:
|
||||
- suspicious input marks the turn as degraded instead of silently continuing
|
||||
- dangerous input is blocked
|
||||
- clean input remains unchanged
|
||||
|
||||
Prefer tests that assert on a security decision object instead of brittle prompt strings.
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs prompt_guard -- --nocapture
|
||||
cargo test -p zeroclawlabs agent -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because no entry path consumes the guard result.
|
||||
|
||||
**Step 3: Implement guarded entry evaluation**
|
||||
|
||||
Before each turn:
|
||||
- scan the inbound user content
|
||||
- map the guard result into `GuardRisk`
|
||||
- create an execution context carrying risk and provenance
|
||||
- attach audit details for later logging
|
||||
|
||||
Keep the existing `PromptGuard` regexes unless a test demands a specific adjustment.
|
||||
|
||||
**Step 4: Re-run the tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs prompt_guard -- --nocapture
|
||||
cargo test -p zeroclawlabs agent -- --nocapture
|
||||
```
|
||||
|
||||
Expected: suspicious and blocked paths now behave deterministically.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/security/prompt_guard.rs third_party/zeroclaw/src/agent/agent.rs third_party/zeroclaw/src/gateway/mod.rs third_party/zeroclaw/src/gateway/ws.rs
|
||||
git commit -m "feat: enforce prompt guard at runtime entry points"
|
||||
```
|
||||
|
||||
### Task 6: Add Business-Level Privileged Operation Registry and Approval Tokens
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/approval/mod.rs`
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/business_approval.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/mod.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/security/business_approval.rs`
|
||||
|
||||
**Step 1: Write failing business approval tests**
|
||||
|
||||
Add tests that prove:
|
||||
- only operations in the privileged registry can request approval
|
||||
- approval tokens bind to `session_id`, `operation_type`, `allowed_capabilities`, `step_budget`, and expiration
|
||||
- a mismatched or expired approval token is rejected
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs business_approval -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because the business approval registry does not exist yet.
|
||||
|
||||
**Step 3: Implement the registry and token model**
|
||||
|
||||
Create:
|
||||
- a privileged business operation registry
|
||||
- a single-operation approval token
|
||||
- helper checks for `can_request_approval` and `matches_execution_request`
|
||||
|
||||
Model approval at the business-operation level, not raw tool calls.
|
||||
|
||||
**Step 4: Extend the existing approval module**
|
||||
|
||||
Teach the approval module to carry business-level fields through the current request/response flow without breaking old call sites.
|
||||
|
||||
**Step 5: Re-run the tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs business_approval -- --nocapture
|
||||
```
|
||||
|
||||
Expected: the token validation and registry tests pass.
|
||||
|
||||
**Step 6: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/approval/mod.rs third_party/zeroclaw/src/security/mod.rs third_party/zeroclaw/src/security/business_approval.rs
|
||||
git commit -m "feat: add business-level approval registry"
|
||||
```
|
||||
|
||||
### Task 7: Enforce Execution Modes in Tool Dispatch
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/dispatcher.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/agent.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/loop_.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/dispatcher.rs`
|
||||
|
||||
**Step 1: Write failing dispatcher tests**
|
||||
|
||||
Add tests that prove:
|
||||
- `suspect_readonly` allows only safe read capabilities
|
||||
- `trusted_skill` can execute capabilities listed in its metadata within `step_budget`
|
||||
- `mixed` or non-skill privileged calls require a matching business approval token
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs dispatcher -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because the dispatcher does not yet know about execution modes.
|
||||
|
||||
**Step 3: Implement capability enforcement**
|
||||
|
||||
Before dispatching any tool:
|
||||
- resolve the operation context
|
||||
- map the tool call to a capability class
|
||||
- reject calls outside the current execution mode
|
||||
- decrement or validate `step_budget` for approved bounded flows
|
||||
|
||||
Do not rely on prompt text for enforcement.
|
||||
|
||||
**Step 4: Re-run the tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs dispatcher -- --nocapture
|
||||
```
|
||||
|
||||
Expected: dispatch now respects read-only, trusted skill, and business-approved modes.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/agent/dispatcher.rs third_party/zeroclaw/src/agent/agent.rs third_party/zeroclaw/src/agent/loop_.rs
|
||||
git commit -m "feat: enforce execution mode in tool dispatch"
|
||||
```
|
||||
|
||||
### Task 8: Default Skills Prompt Injection to Compact for Safer Runtime Behavior
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/config/schema.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/prompt.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/channels/mod.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/config/schema.rs`
|
||||
|
||||
**Step 1: Write the failing configuration test**
|
||||
|
||||
Add a test that asserts the default skill prompt injection mode is `Compact` unless explicitly configured otherwise.
|
||||
|
||||
**Step 2: Run the test to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs skills_prompt_injection_mode -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because defaults still point to `Full`.
|
||||
|
||||
**Step 3: Implement the default flip**
|
||||
|
||||
Update config defaults and any prompt-builder defaults that currently assume `Full`. Keep explicit user config backward compatible.
|
||||
|
||||
**Step 4: Re-run the test to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs skills_prompt_injection_mode -- --nocapture
|
||||
```
|
||||
|
||||
Expected: default configuration now resolves to `Compact`.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/config/schema.rs third_party/zeroclaw/src/agent/prompt.rs third_party/zeroclaw/src/channels/mod.rs
|
||||
git commit -m "feat: default skills prompt injection to compact"
|
||||
```
|
||||
|
||||
### Task 9: Add Audit Logging and Regression Coverage
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/observability/mod.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/agent/agent.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/src/channels/mod.rs`
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/third_party/zeroclaw/tests/prompt_safety_regression.rs`
|
||||
|
||||
**Step 1: Write the failing regression tests**
|
||||
|
||||
Cover:
|
||||
- prompt override attack from user content
|
||||
- malicious `AGENTS.md` bootstrap content
|
||||
- trusted skill execution within bounds
|
||||
- non-skill privileged request requiring business approval
|
||||
- approval token mismatch
|
||||
- session history restore preserving degraded mode
|
||||
|
||||
**Step 2: Run the tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs --test prompt_safety_regression -- --nocapture
|
||||
```
|
||||
|
||||
Expected: fail because the end-to-end behavior is not wired together yet.
|
||||
|
||||
**Step 3: Implement audit logging**
|
||||
|
||||
Record:
|
||||
- input hash
|
||||
- matched guard rules
|
||||
- risk level
|
||||
- provenance
|
||||
- execution mode transitions
|
||||
- approval decisions
|
||||
|
||||
Avoid logging raw sensitive content.
|
||||
|
||||
**Step 4: Re-run the regression tests to verify GREEN**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs --test prompt_safety_regression -- --nocapture
|
||||
```
|
||||
|
||||
Expected: the regression suite passes.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add third_party/zeroclaw/src/observability/mod.rs third_party/zeroclaw/src/agent/agent.rs third_party/zeroclaw/src/channels/mod.rs third_party/zeroclaw/tests/prompt_safety_regression.rs
|
||||
git commit -m "test: add prompt safety regression coverage"
|
||||
```
|
||||
|
||||
### Task 10: Final Verification and Integration Review
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/docs/L5-提示词分布与安全改造方案.md`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening/docs/README.md`
|
||||
|
||||
**Step 1: Run targeted verification**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-prompt-safety-hardening
|
||||
cargo test -p zeroclawlabs prompt_guard -- --nocapture
|
||||
cargo test -p zeroclawlabs build_system_prompt -- --nocapture
|
||||
cargo test -p zeroclawlabs dispatcher -- --nocapture
|
||||
cargo test -p zeroclawlabs --test prompt_safety_regression -- --nocapture
|
||||
```
|
||||
|
||||
Expected: all prompt safety and dispatcher tests pass.
|
||||
|
||||
**Step 2: Run a broad ZeroClaw package test pass if time permits**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cargo test -p zeroclawlabs -- --nocapture
|
||||
```
|
||||
|
||||
Expected: no regressions in the vendored package test suite, or a documented list of unrelated existing failures.
|
||||
|
||||
**Step 3: Update the security design docs**
|
||||
|
||||
Document:
|
||||
- execution modes
|
||||
- trusted skill metadata contract
|
||||
- business approval flow
|
||||
- why non-skill privileged actions are gated
|
||||
|
||||
**Step 4: Commit the docs**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add docs/L5-提示词分布与安全改造方案.md docs/README.md
|
||||
git commit -m "docs: record prompt safety hardening design"
|
||||
```
|
||||
|
||||
**Step 5: Prepare merge review notes**
|
||||
|
||||
Write a short integration summary covering:
|
||||
- changed entry points
|
||||
- backward-compatibility expectations
|
||||
- any skills that need metadata upgrades
|
||||
- rollout recommendation for existing integrators
|
||||
179
docs/plans/2026-03-27-sgclaw-chat-first-ui-refactor-plan.md
Normal file
179
docs/plans/2026-03-27-sgclaw-chat-first-ui-refactor-plan.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# sgClaw Chat-First UI Refactor Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Rebuild the sgClaw floating chat UI into a chat-first plugin-style product where the message timeline is primary, `执行摘要` is folded into the conversation, and `调试` opens as a full-window overlay instead of occupying persistent space.
|
||||
|
||||
**Architecture:** Keep `chrome://superrpa-functions/sgclaw-chat` as the first verified host because it already has Lit-based unit tests, then mirror the same information architecture and visual hierarchy into the ordinary-page injected `sgclaw_overlay.js`. Do not introduce a new backend contract; only rearrange presentation, panel semantics, and message/result composition around the existing runtime state.
|
||||
|
||||
**Tech Stack:** Chromium WebUI, Lit templates/components, injected Shadow DOM overlay JavaScript, existing SuperRPA bridge/runtime callbacks, mainline TS unit tests.
|
||||
|
||||
### Task 1: Lock The New Information Architecture In Tests
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
Add assertions for these exact product rules:
|
||||
- `getHtml()` must no longer emit the legacy `debug-note`.
|
||||
- the main chat template must define a dedicated overlay/sheet container for `history`, `settings`, and `debug`.
|
||||
- the debug panel must be described as a full-window overlay rather than a side drawer/log block.
|
||||
- the result presentation must be part of the message stream, not a standalone persistent secondary panel.
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
node --test /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
|
||||
```
|
||||
|
||||
Expected: FAIL because current template still includes `debug-note`, side-by-side panel layout, and standalone result panel semantics.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Change only template/component strings and assertions needed to express the new structure, without touching styling yet.
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run the same command.
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
### Task 2: Refactor `chrome://` sgClaw Into Chat-First Structure
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-header.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-composer.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-debug-drawer.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-history-panel.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-settings-panel.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-list.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-result.ts`
|
||||
|
||||
**Step 1: Keep the header narrow**
|
||||
|
||||
Make the header carry only:
|
||||
- brand
|
||||
- current page label
|
||||
- compact runtime status
|
||||
- actions for `新对话 / 历史 / 设置 / 调试 / 收起`
|
||||
|
||||
Remove the large subtitle/debug framing and the separate heavy runtime action row feel.
|
||||
|
||||
**Step 2: Make the message timeline primary**
|
||||
|
||||
Turn the main shell body into:
|
||||
- a single timeline container
|
||||
- optional empty-state presets
|
||||
- no persistent secondary summary card
|
||||
|
||||
`finalResult` should render as a folded result card appended in the stream.
|
||||
|
||||
**Step 3: Convert secondary panels into full overlays**
|
||||
|
||||
Render `history`, `settings`, and `debug` inside a full-window overlay/sheet that covers the chat content area instead of sitting above or beside it.
|
||||
|
||||
**Step 4: Re-skin toward the approved direction**
|
||||
|
||||
Use:
|
||||
- soft neutral surfaces
|
||||
- restrained accent usage
|
||||
- thinner borders
|
||||
- calmer shadows
|
||||
- clearer assistant/user card contrast
|
||||
|
||||
Avoid:
|
||||
- debug-workbench feeling
|
||||
- large gradient blocks
|
||||
- heavy explanatory copy in the main flow
|
||||
|
||||
**Step 5: Run the unit tests**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
node --test /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
### Task 3: Mirror The Same Structure Into Ordinary-Page Overlay
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js`
|
||||
|
||||
**Step 1: Remove the standalone result panel**
|
||||
|
||||
Delete the always-visible `执行摘要` block from the main window body.
|
||||
|
||||
**Step 2: Introduce overlay panels**
|
||||
|
||||
Change panel rendering so `history`, `settings`, and `debug` appear in a dedicated full-window overlay layer within the floating window instead of as sibling blocks consuming vertical space.
|
||||
|
||||
**Step 3: Rebuild the shell**
|
||||
|
||||
Match the `chrome://` layout:
|
||||
- compact header
|
||||
- primary message timeline
|
||||
- folded result card inside conversation
|
||||
- sticky composer
|
||||
|
||||
**Step 4: Preserve behavior**
|
||||
|
||||
Do not break:
|
||||
- `sgclaw.newConversation`
|
||||
- `sgclaw.restoreConversation`
|
||||
- runtime polling
|
||||
- config save/load
|
||||
- unread badge behavior
|
||||
|
||||
**Step 5: Run a syntax sanity check**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
### Task 4: Verify Browser Resource Integration
|
||||
|
||||
**Files:**
|
||||
- No new source files; verification only
|
||||
|
||||
**Step 1: Run TS / mainline tests**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
bash -lc "autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests"
|
||||
```
|
||||
|
||||
Expected: build succeeds.
|
||||
|
||||
**Step 2: Run targeted mainline unit tests**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests --gtest_filter='FunctionsUiMainlineTest.*sgclaw*'
|
||||
```
|
||||
|
||||
If filter finds no test names, run the full binary and confirm it exits `0`.
|
||||
|
||||
**Step 3: Rebuild browser resources if needed**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
bash -lc "autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome"
|
||||
```
|
||||
|
||||
**Step 4: Manually verify product behavior**
|
||||
|
||||
Check:
|
||||
- ordinary webpage floating window
|
||||
- `chrome://superrpa-functions/sgclaw-chat`
|
||||
- `调试` opens as full overlay
|
||||
- `执行摘要` no longer blocks the main conversation
|
||||
- `历史` and `设置` do not consume persistent layout space
|
||||
148
docs/plans/2026-03-27-sgclaw-configurable-skills-dir-plan.md
Normal file
148
docs/plans/2026-03-27-sgclaw-configurable-skills-dir-plan.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# SGClaw Configurable Skills Directory Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Let `sgclaw` own skill-directory resolution and allow users to set a custom skills directory in `sgclaw_config.json` without relying on SuperRPA to copy skills into the runtime workspace.
|
||||
|
||||
**Architecture:** Extend the existing browser JSON config parser so `sgclaw` can read an optional `skillsDir` field alongside DeepSeek settings. Keep the current embedded ZeroClaw workspace for memory/config internals, but decouple skill loading from that fixed path by resolving a configurable skills root at runtime. Preserve backward compatibility by defaulting to `<workspace_root>/.sgclaw-zeroclaw-workspace/skills` when `skillsDir` is absent or empty.
|
||||
|
||||
**Tech Stack:** Rust, serde JSON parsing, existing ZeroClaw compatibility runtime, cargo test
|
||||
|
||||
### Task 1: Capture browser config requirements
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/src/config/settings.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/tests/compat_config_test.rs`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
Add tests that load `sgclaw_config.json` containing:
|
||||
- no `skillsDir`
|
||||
- a relative `skillsDir`
|
||||
- an absolute `skillsDir`
|
||||
|
||||
Assert that:
|
||||
- `skillsDir` missing falls back to default workspace skills path
|
||||
- relative values resolve against the browser config directory
|
||||
- absolute values are preserved
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cargo test compat_config -- --nocapture`
|
||||
|
||||
Expected: FAIL because `DeepSeekSettings` / config adapter do not expose any skills directory override yet.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Add a browser-config structure that parses `skillsDir` and expose a resolver function that returns the effective skills directory for `sgclaw`.
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cargo test compat_config -- --nocapture`
|
||||
|
||||
Expected: PASS for the new parsing and path-resolution cases.
|
||||
|
||||
### Task 2: Route compat runtime skill loading through sgclaw-owned resolution
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/src/compat/config_adapter.rs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/tests/compat_runtime_test.rs`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
Add a compat runtime test that creates:
|
||||
- a default workspace skill package under `.sgclaw-zeroclaw-workspace/skills`
|
||||
- a custom skill package under another directory configured via `skillsDir`
|
||||
|
||||
Assert that provider request payload contains only the configured skill name when `skillsDir` is set, and still contains workspace skill names when the override is absent.
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cargo test compat_runtime -- --nocapture`
|
||||
|
||||
Expected: FAIL because the runtime currently always loads skills from `config.workspace_dir`.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Keep `config.workspace_dir` for ZeroClaw internal state, but load skills from the resolved effective skills directory by calling `load_skills_from_directory` directly when a custom directory is configured.
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cargo test compat_runtime -- --nocapture`
|
||||
|
||||
Expected: PASS and provider request payload shows the right `Available Skills` content.
|
||||
|
||||
### Task 3: Document and verify backward compatibility
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/docs/README.md`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/docs/L5-提示词分布与安全改造方案.md`
|
||||
|
||||
**Step 1: Write the failing check**
|
||||
|
||||
Record the expected runtime behavior:
|
||||
- `sgclaw` owns skill lookup
|
||||
- SuperRPA only passes `--config-path`
|
||||
- `skillsDir` is optional
|
||||
|
||||
**Step 2: Run verification**
|
||||
|
||||
Run: `rg -n "skillsDir|sgclaw owns skill lookup|config-path" docs`
|
||||
|
||||
Expected: missing text before docs are updated.
|
||||
|
||||
**Step 3: Write minimal documentation**
|
||||
|
||||
Document:
|
||||
- JSON field name
|
||||
- relative-path resolution base
|
||||
- default fallback
|
||||
- operational implication for SuperRPA integration
|
||||
|
||||
**Step 4: Run verification**
|
||||
|
||||
Run: `rg -n "skillsDir|sgclaw owns skill lookup|config-path" docs`
|
||||
|
||||
Expected: PASS with updated docs.
|
||||
|
||||
### Task 4: Final verification
|
||||
|
||||
**Files:**
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/src/config/settings.rs`
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/src/compat/config_adapter.rs`
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs`
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/tests/compat_config_test.rs`
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/tests/compat_runtime_test.rs`
|
||||
|
||||
**Step 1: Run targeted tests**
|
||||
|
||||
Run: `cargo test compat_config -- --nocapture`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
**Step 2: Run runtime tests**
|
||||
|
||||
Run: `cargo test compat_runtime -- --nocapture`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
**Step 3: Run skill-lib structural validation**
|
||||
|
||||
Run: `python3 -m unittest tests.skill_lib_validation_test -v`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
**Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/plans/2026-03-27-sgclaw-configurable-skills-dir-plan.md \
|
||||
src/config/settings.rs \
|
||||
src/compat/config_adapter.rs \
|
||||
src/compat/runtime.rs \
|
||||
tests/compat_config_test.rs \
|
||||
tests/compat_runtime_test.rs \
|
||||
docs/README.md \
|
||||
docs/L5-提示词分布与安全改造方案.md
|
||||
git commit -m "feat: make sgclaw skills directory configurable"
|
||||
```
|
||||
624
docs/plans/2026-03-27-sgclaw-floating-chat-frontend-design.md
Normal file
624
docs/plans/2026-03-27-sgclaw-floating-chat-frontend-design.md
Normal file
@@ -0,0 +1,624 @@
|
||||
# sgClaw Floating Chat Frontend Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Replace the current debug-style `sgclaw-chat` UI with a complete floating-chat frontend that matches the product structure of Doubao's side panel while preserving the current SuperRPA bridge and configuration capabilities.
|
||||
|
||||
**Architecture:** Keep `chrome://superrpa-functions/sgclaw-chat` as the first delivery host so the new UI can be built and verified without waiting for the final page-floating container. Split the current monolithic Lit component into host adapter, state modules, typed message model, presentational components, and secondary panels so the same UI can later be mounted in a real injected floating window on normal web pages. Preserve the existing browser bridge (`sgclawConnect`, `sgclawStart`, `sgclawStop`, `sgclawSubmitTask`) and re-home logs/configuration into secondary panels instead of deleting them.
|
||||
|
||||
**Tech Stack:** Chromium WebUI, Lit, existing `FunctionsUI` router, SuperRPA browser bridge callbacks, current `sgclaw-config` config page logic, future floating host injection in SuperRPA.
|
||||
|
||||
## Product Target
|
||||
|
||||
The frontend target is a single-column chat product, not a multi-card debug workstation.
|
||||
|
||||
Final visual structure:
|
||||
|
||||
```text
|
||||
Collapsed Fab
|
||||
┌────────────┐
|
||||
│ sgClaw ●2 │
|
||||
└────────────┘
|
||||
|
||||
Expanded Chat
|
||||
┌──────────────────────────────────────────┐
|
||||
│ sgClaw | 当前网页：example.com │
|
||||
│ [新对话] [历史] [设置] [收起] │
|
||||
│ 状态：待命 / 执行中 / 出错 │
|
||||
├──────────────────────────────────────────┤
|
||||
│ 欢迎区 / 推荐动作 │
|
||||
│ [总结当前页面] [提取表格] [执行网页操作] │
|
||||
├──────────────────────────────────────────┤
|
||||
│ 消息流 │
|
||||
│ 用户消息 │
|
||||
│ 助手消息 │
|
||||
│ 步骤卡 / 结果卡 / 错误卡 │
|
||||
├──────────────────────────────────────────┤
|
||||
│ [网页执行] [页面问答] [页面总结] │
|
||||
│ [上下文开关] [调试] [更多] │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ 输入任务... │ │
|
||||
│ └──────────────────────────────────────┘ │
|
||||
│ [发送]│
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Core UX rules:
|
||||
|
||||
- The primary content area is always the message stream.
|
||||
- `finalResult` becomes a result card inside the message stream.
|
||||
- `logs` move into a hidden debug drawer.
|
||||
- `start/stop` remain available but move to the header status area.
|
||||
- Configuration remains available but opens inside a settings panel first, with route-navigation fallback to `chrome://superrpa-functions/sgclaw-config`.
|
||||
- The same component tree must work in `FunctionsUI` first and later inside a real injected floating host.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope For This Frontend Plan
|
||||
|
||||
- Complete visual redesign of `sgclaw-chat`
|
||||
- Empty state, active chat state, running state, success state, error state
|
||||
- Local conversation history UI
|
||||
- Embedded settings panel
|
||||
- Debug drawer
|
||||
- Stable typed message model
|
||||
- Separation of host bridge code from UI code
|
||||
- Floating launcher state model
|
||||
|
||||
### Explicitly Out Of Scope For First Frontend Delivery
|
||||
|
||||
- Real attachment upload execution
|
||||
- Deep-thinking or multi-skill plugin ecosystem
|
||||
- Provider/protocol redesign on the Rust side
|
||||
- Full page-injected floating host implementation
|
||||
- New backend APIs beyond the current bridge
|
||||
|
||||
## Existing Baseline To Reuse
|
||||
|
||||
The implementation should reuse these existing assets instead of replacing them blindly:
|
||||
|
||||
- Host page routing: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/functions.ts`
|
||||
- Existing chat entry registration: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/functions_manifest.json`
|
||||
- Current chat page bridge logic: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Current floating state prototype: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state.ts`
|
||||
- Current config UI and bridge: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config.ts`
|
||||
|
||||
## Final File Layout
|
||||
|
||||
All implementation paths below are exact and rooted in `/home/zyl/projects/superRpa/src`.
|
||||
|
||||
### Core Chat Entry
|
||||
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
|
||||
|
||||
### State Modules
|
||||
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_conversation_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_state.ts`
|
||||
|
||||
### Host Adapter
|
||||
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_host_adapter.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge.ts`
|
||||
|
||||
### Message Model And Rendering
|
||||
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_messages.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-list.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-user.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-assistant.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-step.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-result.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-error.ts`
|
||||
|
||||
### Shell Components
|
||||
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-shell.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-header.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-composer.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-history-panel.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-settings-panel.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-debug-drawer.ts`
|
||||
|
||||
### Build And Host Wiring
|
||||
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/BUILD.gn`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/functions.html.ts`
|
||||
|
||||
### Tests
|
||||
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state_mainline_unittest.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state_mainline_unittest.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state_mainline_unittest.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge_mainline_unittest.ts`
|
||||
|
||||
## Target State Model
|
||||
|
||||
Use a typed model instead of the current loose shape.
|
||||
|
||||
```ts
|
||||
interface SgClawChatWindowState {
|
||||
windowOpen: boolean;
|
||||
activePanel: 'chat' | 'history' | 'settings' | 'debug';
|
||||
unreadCount: number;
|
||||
}
|
||||
|
||||
interface SgClawChatConversationState {
|
||||
conversationId: string;
|
||||
draftInput: string;
|
||||
mode: 'web-action' | 'page-qa' | 'page-summary';
|
||||
contextEnabled: boolean;
|
||||
messages: SgClawMessage[];
|
||||
}
|
||||
|
||||
interface SgClawMessage {
|
||||
id: string;
|
||||
type: 'user_text' | 'assistant_text' | 'task_step' | 'task_result' | 'task_error' | 'system_notice';
|
||||
role: 'user' | 'assistant' | 'system';
|
||||
content: string;
|
||||
status?: 'pending' | 'running' | 'done' | 'failed';
|
||||
timestamp: number;
|
||||
meta?: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
|
||||
The current `logs`, `messages`, `finalResult`, `pendingReply`, and `busy` state should be re-expressed through these typed stores instead of being owned directly by the entry component.
|
||||
|
||||
## Task 1: Freeze The Current Entry And Enable Real Template/CSS Modules
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing structure test**
|
||||
|
||||
Add assertions that the entry no longer hardcodes the full DOM layout in `render()` and imports its shell template/style helpers.
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease sgclaw-chat_build_ts
|
||||
```
|
||||
|
||||
Expected: fail because `sgclaw-chat.html.ts` and `sgclaw-chat.css.ts` are empty and the new test expects real exports.
|
||||
|
||||
**Step 3: Write the minimal implementation**
|
||||
|
||||
- Move root shell markup to `getHtml()`
|
||||
- Move root style tokens/layout to `getCss()`
|
||||
- Keep `sgclaw-chat.ts` focused on state + events
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: TS build succeeds and the entry uses external template/style helpers.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "refactor: extract sgclaw chat shell template"
|
||||
```
|
||||
|
||||
## Task 2: Build The Window, Conversation, History, And Settings State Modules
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_conversation_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_state.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state_mainline_unittest.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state_mainline_unittest.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state_mainline_unittest.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing pure-state tests**
|
||||
|
||||
Cover:
|
||||
- open/close/switch panel transitions
|
||||
- unread count clear on open
|
||||
- create/reset conversation
|
||||
- local history push/select/remove
|
||||
- settings draft dirty detection
|
||||
|
||||
**Step 2: Run tests to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease sgclaw-chat_build_ts
|
||||
```
|
||||
|
||||
Expected: build fails because the new modules and tests do not exist yet.
|
||||
|
||||
**Step 3: Write the minimal implementation**
|
||||
|
||||
Implement pure functions only. Do not mix DOM work into these modules.
|
||||
|
||||
**Step 4: Run tests to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: all pure-state modules compile and their tests pass.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_conversation_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-floating_state_mainline_unittest.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_window_state_mainline_unittest.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state_mainline_unittest.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "feat: add sgclaw chat state modules"
|
||||
```
|
||||
|
||||
## Task 3: Introduce A Host Adapter So UI Stops Owning Bridge Details
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_host_adapter.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing bridge test**
|
||||
|
||||
Test that:
|
||||
- `connect()` issues `sgclawConnect`
|
||||
- `start()` issues `sgclawStart`
|
||||
- `stop()` issues `sgclawStop`
|
||||
- `submitTask()` issues `sgclawSubmitTask`
|
||||
- callback payload parsing is handled in one place
|
||||
|
||||
**Step 2: Run test to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease sgclaw-chat_build_ts
|
||||
```
|
||||
|
||||
Expected: fail because adapter modules do not exist.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Wrap `chrome.send`
|
||||
- Centralize callback registration
|
||||
- Return typed runtime events/state to the UI layer
|
||||
|
||||
**Step 4: Run test to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: adapter tests compile and pass.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_host_adapter.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_runtime_bridge_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "refactor: isolate sgclaw chat host bridge"
|
||||
```
|
||||
|
||||
## Task 4: Replace The Loose Message Format With Typed Cards In The Message Stream
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_messages.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-list.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-user.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-assistant.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-step.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-result.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-error.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing rendering test**
|
||||
|
||||
Add expectations that:
|
||||
- empty state shows guidance instead of a blank box
|
||||
- `task_complete` renders a result card in the message stream
|
||||
- `error` renders an error card in the message stream
|
||||
- `pendingReply` renders an assistant pending card
|
||||
|
||||
**Step 2: Run test to verify RED**
|
||||
|
||||
Run the TS build target.
|
||||
|
||||
Expected: fail because message types and card components do not exist.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Keep the message list single-column
|
||||
- Preserve current user/assistant turn behavior
|
||||
- Move `finalResult` handling into result-card rendering
|
||||
- Move error display into message flow
|
||||
|
||||
**Step 4: Run test to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: cards render correctly and the old standalone result area is no longer required.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_messages.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-list.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-user.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-assistant.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-step.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-result.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-error.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "feat: add sgclaw chat message cards"
|
||||
```
|
||||
|
||||
## Task 5: Build The Real Header, Empty State, And Composer
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-shell.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-header.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-composer.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing shell test**
|
||||
|
||||
Assert that the rendered page now contains:
|
||||
- header with title, current page label, and status pill
|
||||
- empty state recommendation buttons
|
||||
- fixed composer at the bottom
|
||||
- no standalone `实时日志` or `最终结果` primary sections
|
||||
|
||||
**Step 2: Run test to verify RED**
|
||||
|
||||
Run the TS build target.
|
||||
|
||||
Expected: fail because the shell components do not exist.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Header: title, page context, new-chat/history/settings/collapse actions
|
||||
- Empty state: 3 to 4 recommended actions
|
||||
- Composer: text input, send button, mode toggles, context switch
|
||||
|
||||
**Step 4: Run test to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: the page renders as a product-style chat shell.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-shell.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-header.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-composer.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "feat: add sgclaw chat shell and composer"
|
||||
```
|
||||
|
||||
## Task 6: Embed Settings And Move Raw Logs Into A Debug Drawer
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-settings-panel.ts`
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-debug-drawer.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
|
||||
- Reuse Read-Only Reference: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-config/sgclaw-config.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing panel tests**
|
||||
|
||||
Cover:
|
||||
- opening settings panel from header
|
||||
- editing embedded config draft
|
||||
- opening debug drawer and showing logs
|
||||
- closing secondary panels without destroying the chat draft
|
||||
|
||||
**Step 2: Run test to verify RED**
|
||||
|
||||
Run the TS build target.
|
||||
|
||||
Expected: fail because secondary panel components do not exist.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Reuse config field structure from `sgclaw-config`
|
||||
- Keep raw logs in debug only
|
||||
- Preserve route-navigation fallback for full config page if embedded save/load fails
|
||||
|
||||
**Step 4: Run test to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: settings and debug layers behave as secondary panels instead of separate pages.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-settings-panel.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-debug-drawer.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "feat: add sgclaw settings panel and debug drawer"
|
||||
```
|
||||
|
||||
## Task 7: Add Local Conversation History And New-Chat Recovery
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-history-panel.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state_mainline_unittest.ts`
|
||||
|
||||
**Step 1: Write the failing history tests**
|
||||
|
||||
Cover:
|
||||
- saving a conversation preview to local history
|
||||
- creating a fresh conversation resets message stream but keeps config
|
||||
- reopening a history item restores messages and draft
|
||||
|
||||
**Step 2: Run test to verify RED**
|
||||
|
||||
Run the TS build target.
|
||||
|
||||
Expected: fail because history panel and persistence behavior do not exist.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Store history locally in browser storage or localStorage
|
||||
- Keep only small metadata + message snapshot for first version
|
||||
- No backend schema change in this phase
|
||||
|
||||
**Step 4: Run test to verify GREEN**
|
||||
|
||||
Run the same build target.
|
||||
|
||||
Expected: local conversation switching works fully in the frontend.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-history-panel.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_history_state_mainline_unittest.ts
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "feat: add sgclaw local conversation history"
|
||||
```
|
||||
|
||||
## Task 8: Wire New Shell Assets Into BUILD And Polish The Host Page
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/BUILD.gn`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/functions.html.ts`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/functions.css`
|
||||
|
||||
**Step 1: Write the failing host expectation**
|
||||
|
||||
Add a small host-level check that:
|
||||
- `sgclaw-chat` still loads from the manifest
|
||||
- host quick actions still work
|
||||
- the function page provides enough room for the new chat shell
|
||||
|
||||
**Step 2: Run test/build to verify RED**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease sgclaw-chat_build_ts
|
||||
```
|
||||
|
||||
Expected: fail or render incorrectly because new component files are not all wired into build/host styling yet.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
- Add all new TS modules to `BUILD.gn`
|
||||
- Keep `sgclaw-chat` and `sgclaw-config` quick actions
|
||||
- Adjust host layout so the new shell is not boxed into the old debug-page proportions
|
||||
|
||||
**Step 4: Run verification**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease sgclaw-chat_build_ts
|
||||
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease superrpa_resources
|
||||
```
|
||||
|
||||
Expected: build completes with all new chat modules wired in.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git -C /home/zyl/projects/superRpa/src add \
|
||||
chrome/browser/resources/superrpa/devtools/BUILD.gn \
|
||||
chrome/browser/resources/superrpa/devtools/functions/functions.html.ts \
|
||||
chrome/browser/resources/superrpa/devtools/functions/functions.css
|
||||
git -C /home/zyl/projects/superRpa/src commit -m "chore: wire sgclaw chat frontend modules"
|
||||
```
|
||||
|
||||
## Manual Verification Matrix
|
||||
|
||||
Run all manual checks in `chrome://superrpa-functions/sgclaw-chat` after the full frontend plan lands.
|
||||
|
||||
### UX States
|
||||
|
||||
- Empty state appears on first open.
|
||||
- Recommended actions generate user messages.
|
||||
- Composer stays visible while history/settings/debug panels switch.
|
||||
- Message stream auto-scrolls to the latest item.
|
||||
- Result cards and error cards appear inline.
|
||||
|
||||
### Runtime
|
||||
|
||||
- `启动` works from the header area.
|
||||
- `停止` works from the header area.
|
||||
- submit creates an immediate user message.
|
||||
- pending assistant card appears while waiting.
|
||||
- result card replaces the old standalone result behavior.
|
||||
|
||||
### Settings
|
||||
|
||||
- embedded settings loads existing values
|
||||
- save updates status and clears dirty state
|
||||
- fallback route to `chrome://superrpa-functions/sgclaw-config` still works
|
||||
|
||||
### Debug
|
||||
|
||||
- logs are not visible in the main chat view
|
||||
- debug drawer shows raw logs when opened
|
||||
|
||||
### History
|
||||
|
||||
- new conversation starts clean
|
||||
- previous conversation can be restored from local history
|
||||
- unread badge clears when reopening the window
|
||||
|
||||
## Execution Notes
|
||||
|
||||
- Keep the current backend/runtime bridge unchanged until the new frontend shell is stable.
|
||||
- Do not combine page-injected floating host work into this same branch. The first milestone is a complete product-grade frontend inside the existing `FunctionsUI` host.
|
||||
- When this frontend plan is complete, the next plan should focus only on mounting the same component tree inside a real page floating container.
|
||||
|
||||
Plan complete and saved to `docs/plans/2026-03-27-sgclaw-floating-chat-frontend-design.md`. Two execution options:
|
||||
|
||||
**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
|
||||
|
||||
**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
|
||||
|
||||
**Which approach?**
|
||||
@@ -0,0 +1,85 @@
|
||||
# sgClaw Overlay And Basic Navigation Fixes Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Make ordinary webpages render the new sgClaw floating chat design and support base navigation instructions like `打开知乎`.
|
||||
|
||||
**Architecture:** Keep the ordinary-page injection entrypoint unchanged, but replace its in-shadow DOM layout with the same floating-window shell used by the new debug page. On the runtime side, extend the deterministic planner with explicit homepage navigation plans for supported sites so freeform open-site commands do not fail before the compat runtime can help.
|
||||
|
||||
**Tech Stack:** Chromium WebUI resource pipeline, injected Shadow DOM overlay JavaScript, Rust planner tests
|
||||
|
||||
### Task 1: Lock the current regressions with failing tests
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs`
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/tests/planner_test.rs`
|
||||
|
||||
**Step 1: Write the failing smoke expectations**
|
||||
|
||||
Add assertions that the ordinary webpage overlay shows the new subtitle `面向当前网页的悬浮式对话与自动执行` and no longer exposes the old card titles like `聊天记录`.
|
||||
|
||||
**Step 2: Run the smoke to verify it fails**
|
||||
|
||||
Run: `node /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs`
|
||||
Expected: FAIL because ordinary webpages still render the old overlay shell.
|
||||
|
||||
**Step 3: Write the failing planner test**
|
||||
|
||||
Add a test asserting `plan_instruction("打开知乎")` returns one `Navigate` step to `https://www.zhihu.com`.
|
||||
|
||||
**Step 4: Run the planner test to verify it fails**
|
||||
|
||||
Run: `cargo test planner_supports_open_zhihu_homepage_instruction --test planner_test`
|
||||
Expected: FAIL with `unsupported instruction: 打开知乎`.
|
||||
|
||||
### Task 2: Migrate the ordinary webpage overlay to the new shell
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js`
|
||||
- Test: `/home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs`
|
||||
|
||||
**Step 1: Replace the old card layout with the new floating shell**
|
||||
|
||||
Keep bridge calls, ids, and polling behavior intact, but render the new header, message pane, composer, settings panel, and debug drawer structure inside the existing injected Shadow DOM.
|
||||
|
||||
**Step 2: Keep runtime visibility without reintroducing the old layout**
|
||||
|
||||
Move logs and final result into secondary panels or inline cards so the ordinary webpage still exposes execution details without the old four-card layout.
|
||||
|
||||
**Step 3: Run the smoke again**
|
||||
|
||||
Run: `node /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs`
|
||||
Expected: PASS once rebuilt resources are being served by the browser binary.
|
||||
|
||||
### Task 3: Extend planner support for basic open-site commands
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/claw/src/agent/planner.rs`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/tests/planner_test.rs`
|
||||
|
||||
**Step 1: Implement the minimal homepage plans**
|
||||
|
||||
Support `打开知乎` and `打开百度` by returning single-step `Navigate` plans to their homepages.
|
||||
|
||||
**Step 2: Run planner tests**
|
||||
|
||||
Run: `cargo test --test planner_test`
|
||||
Expected: PASS.
|
||||
|
||||
### Task 4: Build and verify the integrated behavior
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/superRpa/src/AGENTS.md`
|
||||
- Modify: `/home/zyl/projects/superRpa/src/docs/handoffs/2026-03-27-sgclaw-runtime-verification.md`
|
||||
|
||||
**Step 1: Rebuild impacted targets**
|
||||
|
||||
Run: `autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome/browser/resources/superrpa:resources sgclaw`
|
||||
|
||||
**Step 2: Re-run targeted verification**
|
||||
|
||||
Run the smoke and a focused `sgclaw` task submission check for `打开知乎`.
|
||||
|
||||
**Step 3: Document the final runtime path**
|
||||
|
||||
Record that ordinary webpages and `chrome://superrpa-functions/sgclaw-chat` now share the same floating shell, and that homepage navigation commands are handled by the planner.
|
||||
158
docs/plans/2026-03-27-skill-lib-testing-plan.md
Normal file
158
docs/plans/2026-03-27-skill-lib-testing-plan.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Skill Lib Testing Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Add an in-project, repeatable test harness that validates `/home/zyl/projects/sgClaw/skill_lib` against the current ZeroClaw `SKILL.md` loader and security-audit expectations.
|
||||
|
||||
**Architecture:** Keep the test runner inside the SGClaw repository and target the sibling `skill_lib` directory by relative path. Implement a small Python validator that mirrors the ZeroClaw markdown frontmatter parser and the relevant skill-audit checks, then cover it with a Python `unittest` suite that exercises the actual three migrated Zhihu skills.
|
||||
|
||||
**Tech Stack:** Python 3 standard library, `unittest`, local file-system inspection, ZeroClaw source code as behavioral reference, Markdown/YAML-like frontmatter parsing.
|
||||
|
||||
### Task 1: Freeze The Test Contract
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/docs/plans/2026-03-27-skill-lib-testing-plan.md`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/src/skills/mod.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/src/skills/audit.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/skill_lib/skills/*/SKILL.md`
|
||||
|
||||
**Step 1: Capture the loader semantics to preserve**
|
||||
|
||||
Document and implement tests for:
|
||||
- `SKILL.md` frontmatter splitting on `---`
|
||||
- supported metadata keys: `name`, `description`, `version`, `author`, `tags`
|
||||
- fallback rules for name, description, and version
|
||||
- prompt body must exclude the frontmatter block
|
||||
|
||||
**Step 2: Capture the audit semantics to preserve**
|
||||
|
||||
Document and implement tests for:
|
||||
- skill root must contain `SKILL.md` or `SKILL.toml`
|
||||
- symlinks are rejected
|
||||
- shell-script files are blocked when `allow_scripts` is false
|
||||
- markdown links must not escape the skill root
|
||||
- high-risk command snippets inside markdown are rejected
|
||||
|
||||
**Step 3: Define the migrated-skill expectations**
|
||||
|
||||
The test suite must verify:
|
||||
- exactly three skill packages exist
|
||||
- the loaded names are `zhihu-hotlist`, `zhihu-navigate`, `zhihu-write`
|
||||
- each package has both `references/` and `assets/`
|
||||
- each description stays trigger-oriented and starts with `Use when`
|
||||
|
||||
### Task 2: Write The Failing Tests First
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/tests/skill_lib_validation_test.py`
|
||||
|
||||
**Step 1: Write a failing import-level test**
|
||||
|
||||
Import a not-yet-created validator module from:
|
||||
- `/home/zyl/projects/sgClaw/claw/scripts/validate_skill_lib.py`
|
||||
|
||||
Expected initial failure:
|
||||
- `ModuleNotFoundError` or `FileNotFoundError`
|
||||
|
||||
**Step 2: Encode the project expectations**
|
||||
|
||||
Add tests for:
|
||||
- skill discovery count and names
|
||||
- parsed metadata for each current skill
|
||||
- audit cleanliness for each skill with `allow_scripts=False`
|
||||
- package shape (`SKILL.md`, `references/`, `assets/`)
|
||||
|
||||
**Step 3: Run the tests and watch them fail**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
python3 -m unittest tests.skill_lib_validation_test -v
|
||||
```
|
||||
|
||||
Expected:
|
||||
- failure because the validator module does not exist yet
|
||||
|
||||
### Task 3: Implement The Minimal Validator
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/claw/scripts/validate_skill_lib.py`
|
||||
|
||||
**Step 1: Implement discovery helpers**
|
||||
|
||||
Implement:
|
||||
- repo root resolution
|
||||
- sibling `skill_lib` root resolution
|
||||
- `skills/` directory enumeration
|
||||
|
||||
**Step 2: Implement the markdown loader**
|
||||
|
||||
Implement:
|
||||
- frontmatter split
|
||||
- lightweight frontmatter parsing
|
||||
- description fallback extraction
|
||||
- metadata normalization into a `SkillRecord`
|
||||
|
||||
**Step 3: Implement the relevant audit checks**
|
||||
|
||||
Implement:
|
||||
- symlink detection
|
||||
- blocked shell-script detection
|
||||
- markdown link boundary checks
|
||||
- high-risk snippet detection
|
||||
- deterministic findings collection
|
||||
|
||||
**Step 4: Implement a small CLI**
|
||||
|
||||
Running:
|
||||
```bash
|
||||
python3 scripts/validate_skill_lib.py
|
||||
```
|
||||
|
||||
Should:
|
||||
- print one summary line per skill
|
||||
- exit `0` when all skills pass
|
||||
- exit non-zero when any skill fails
|
||||
|
||||
### Task 4: Run The Tests Green
|
||||
|
||||
**Files:**
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/tests/skill_lib_validation_test.py`
|
||||
- Test: `/home/zyl/projects/sgClaw/claw/scripts/validate_skill_lib.py`
|
||||
|
||||
**Step 1: Re-run the unit tests**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
python3 -m unittest tests.skill_lib_validation_test -v
|
||||
```
|
||||
|
||||
Expected:
|
||||
- all tests pass
|
||||
|
||||
**Step 2: Run the CLI validator**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
python3 scripts/validate_skill_lib.py
|
||||
```
|
||||
|
||||
Expected:
|
||||
- all three skills print `PASS`
|
||||
- process exits `0`
|
||||
|
||||
### Task 5: Document The Verification Entry Point
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/skill_lib/VERIFY.md`
|
||||
|
||||
**Step 1: Add the project-local validation command**
|
||||
|
||||
Add:
|
||||
- `python3 /home/zyl/projects/sgClaw/claw/scripts/validate_skill_lib.py`
|
||||
- `python3 -m unittest /home/zyl/projects/sgClaw/claw/tests/skill_lib_validation_test.py`
|
||||
|
||||
**Step 2: Re-run both commands after the doc update**
|
||||
|
||||
Expected:
|
||||
- validator still exits `0`
|
||||
- unit tests still pass
|
||||
411
docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md
Normal file
411
docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# Skill Lib ZeroClaw Migration Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Create `/home/zyl/projects/sgClaw/skill_lib` as a dedicated skill library directory and restructure the current Zhihu browser capabilities into ZeroClaw-style skill packages.
|
||||
|
||||
**Architecture:** Treat `skill_lib` as a standalone skill repository, not as an embedded Rust module tree. Use the ZeroClaw/open-skills layout `skill_lib/skills/<skill-name>/SKILL.md`, keep each skill self-contained, and move long operational detail into `references/` plus any preserved source artifacts into `assets/`. Map the current four exposed Rust capabilities into three end-user skills: `zhihu-navigate`, `zhihu-write`, and `zhihu-hotlist`.
|
||||
|
||||
**Tech Stack:** Markdown `SKILL.md`, YAML frontmatter, directory-based ZeroClaw skill packaging, existing SGClaw Zhihu Rust/JSON source material, shell validation commands.
|
||||
|
||||
### Task 1: Freeze The Target Layout
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/README.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/src/skills/mod.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/third_party/zeroclaw/skills/browser/SKILL.md`
|
||||
|
||||
**Step 1: Create the top-level repository skeleton**
|
||||
|
||||
Create:
|
||||
- `/home/zyl/projects/sgClaw/skill_lib/README.md`
|
||||
- `/home/zyl/projects/sgClaw/skill_lib/skills/`
|
||||
|
||||
The README should state:
|
||||
- this directory is a dedicated ZeroClaw-style skill library
|
||||
- runtime skill packages live under `skills/<name>/`
|
||||
- each skill package uses `SKILL.md` plus optional `references/`, `scripts/`, and `assets/`
|
||||
|
||||
**Step 2: Document the package contract in the README**
|
||||
|
||||
Include:
|
||||
- required file: `SKILL.md`
|
||||
- supported frontmatter for this repo: `name`, `description`, `version`, `author`, `tags`
|
||||
- design rule: `description` must be trigger-oriented and not a workflow dump
|
||||
- design rule: keep `SKILL.md` concise and push long detail into `references/`
|
||||
|
||||
**Step 3: Run structural sanity checks**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
test -d /home/zyl/projects/sgClaw/skill_lib
|
||||
test -d /home/zyl/projects/sgClaw/skill_lib/skills
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/README.md
|
||||
```
|
||||
|
||||
Expected: all commands exit `0`.
|
||||
|
||||
### Task 2: Define The Skill Inventory And Source Mapping
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skill_inventory.md`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/mod.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/router.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist_store.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_navigation.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_navigation_pages.json`
|
||||
|
||||
**Step 1: Write the migration inventory**
|
||||
|
||||
Create `/home/zyl/projects/sgClaw/skill_lib/skill_inventory.md` with a three-row mapping:
|
||||
- `zhihu-navigate` ← current `zhihu_navigate`
|
||||
- `zhihu-write` ← current `zhihu_write`
|
||||
- `zhihu-hotlist` ← current `zhihu_hotlist_collect` + `zhihu_hotlist_report`
|
||||
|
||||
**Step 2: Capture the non-migrated code responsibilities**
|
||||
|
||||
Document explicitly that this migration does **not** port:
|
||||
- Rust router dispatch
|
||||
- browser pipe transport code
|
||||
- snapshot persistence implementation detail
|
||||
|
||||
Document that the new repo is a skill library, not a Rust runtime.
|
||||
|
||||
**Step 3: Record source artifacts per target skill**
|
||||
|
||||
For each target skill, list:
|
||||
- source Rust module(s)
|
||||
- source JSON flow/catalog file(s)
|
||||
- important risk notes discovered during analysis
|
||||
|
||||
**Step 4: Validate the inventory**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
rg -n "zhihu-navigate|zhihu-write|zhihu-hotlist" /home/zyl/projects/sgClaw/skill_lib/skill_inventory.md
|
||||
```
|
||||
|
||||
Expected: all three skill names appear exactly once as top-level migration targets.
|
||||
|
||||
### Task 3: Author The `zhihu-navigate` Skill Package
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/routes-and-targets.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/selector-strategy.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_navigation.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_navigation_pages.json`
|
||||
|
||||
**Step 1: Preserve the raw source artifact**
|
||||
|
||||
Copy the current navigation catalog into:
|
||||
- `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json`
|
||||
|
||||
This file is for traceability only, not for frontmatter or prompt injection.
|
||||
|
||||
**Step 2: Write the `SKILL.md`**
|
||||
|
||||
Use ZeroClaw-style frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: zhihu-navigate
|
||||
description: Use when the user wants to open, switch, or navigate to a Zhihu page, tab, menu, profile area, notifications area, message area, or creator area through browser actions.
|
||||
version: 0.1.0
|
||||
author: sgclaw
|
||||
tags:
|
||||
- zhihu
|
||||
- browser
|
||||
- navigation
|
||||
---
|
||||
```
|
||||
|
||||
The body should include:
|
||||
- overview
|
||||
- when to use
|
||||
- workflow for route vs component vs flow navigation
|
||||
- ambiguity handling rules
|
||||
- output contract
|
||||
- common mistakes
|
||||
|
||||
**Step 3: Write `routes-and-targets.md`**
|
||||
|
||||
Summarize:
|
||||
- route/component/flow/target model
|
||||
- representative target names
|
||||
- known alias conflicts
|
||||
- preferred disambiguation wording for future prompts
|
||||
|
||||
**Step 4: Write `selector-strategy.md`**
|
||||
|
||||
Document:
|
||||
- why selectors should prefer semantic hooks over CSS hash classes
|
||||
- fallback ordering
|
||||
- known brittle selectors from the current source
|
||||
|
||||
**Step 5: Validate the package**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/routes-and-targets.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/references/selector-strategy.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/assets/zhihu_navigation_pages.source.json
|
||||
```
|
||||
|
||||
Expected: all commands exit `0`.
|
||||
|
||||
### Task 4: Author The `zhihu-write` Skill Package
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/editor-flow.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/publish-safety.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json`
|
||||
|
||||
**Step 1: Preserve the raw source artifact**
|
||||
|
||||
Copy:
|
||||
- `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_write_flow.json`
|
||||
|
||||
to:
|
||||
- `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json`
|
||||
|
||||
**Step 2: Write the `SKILL.md`**
|
||||
|
||||
The frontmatter should name a single skill:
|
||||
- `name: zhihu-write`
|
||||
- description focused on when article drafting or publishing is requested
|
||||
|
||||
The body should include:
|
||||
- prerequisites before touching the editor
|
||||
- workflow for draft-only vs publish
|
||||
- explicit confirmation gate before publish
|
||||
- required final report fields: title, mode, final URL if published, unresolved issues
|
||||
|
||||
**Step 3: Write `editor-flow.md`**
|
||||
|
||||
Document:
|
||||
- entry page
|
||||
- editor readiness checks
|
||||
- title/body fill rules
|
||||
- publish confirmation sequence
|
||||
- URL capture rules
|
||||
|
||||
**Step 4: Write `publish-safety.md`**
|
||||
|
||||
Document:
|
||||
- when to stop and ask for confirmation
|
||||
- what to do if title verification fails
|
||||
- what to do if the URL remains on edit mode
|
||||
- brittle selectors that must be revalidated first
|
||||
|
||||
**Step 5: Validate the package**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/editor-flow.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/references/publish-safety.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/assets/zhihu_write_flow.source.json
|
||||
```
|
||||
|
||||
Expected: all commands exit `0`.
|
||||
|
||||
### Task 5: Author The `zhihu-hotlist` Skill Package
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/collection-flow.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/report-format.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/data-quality.md`
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/src/skill/zhihu_hotlist_store.rs`
|
||||
- Reference only: `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json`
|
||||
|
||||
**Step 1: Preserve the raw source artifact**
|
||||
|
||||
Copy:
|
||||
- `/home/zyl/projects/sgClaw/claw/resources/skills/zhihu_hotlist_flow.json`
|
||||
|
||||
to:
|
||||
- `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json`
|
||||
|
||||
**Step 2: Write the `SKILL.md`**
|
||||
|
||||
Use one skill to cover:
|
||||
- hotlist collection
|
||||
- comment metric collection
|
||||
- snapshot-style reporting
|
||||
|
||||
The body should clearly separate:
|
||||
- collection workflow
|
||||
- report workflow
|
||||
- partial-failure handling
|
||||
- output contract
|
||||
|
||||
**Step 3: Write `collection-flow.md`**
|
||||
|
||||
Include:
|
||||
- hotlist page detection
|
||||
- hotlist HTML capture strategy
|
||||
- top N extraction
|
||||
- detail-page comment collection flow
|
||||
- metric parsing notes
|
||||
|
||||
**Step 4: Write `report-format.md`**
|
||||
|
||||
Define:
|
||||
- report header line
|
||||
- per-item summary line
|
||||
- field names and order
|
||||
- handling when comment metrics are missing
|
||||
|
||||
**Step 5: Write `data-quality.md`**
|
||||
|
||||
Document:
|
||||
- why partial success must be surfaced
|
||||
- what counts as incomplete data
|
||||
- known parser risks
|
||||
- recommended caution language in outputs
|
||||
|
||||
**Step 6: Validate the package**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/collection-flow.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/report-format.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/references/data-quality.md
|
||||
test -f /home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/assets/zhihu_hotlist_flow.source.json
|
||||
```
|
||||
|
||||
Expected: all commands exit `0`.
|
||||
|
||||
### Task 6: Normalize Frontmatter And Trigger Quality
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-navigate/SKILL.md`
|
||||
- Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-write/SKILL.md`
|
||||
- Modify: `/home/zyl/projects/sgClaw/skill_lib/skills/zhihu-hotlist/SKILL.md`
|
||||
|
||||
**Step 1: Normalize frontmatter keys**
|
||||
|
||||
Ensure each `SKILL.md` contains exactly these frontmatter keys in this order:
|
||||
- `name`
|
||||
- `description`
|
||||
- `version`
|
||||
- `author`
|
||||
- `tags`
|
||||
|
||||
Do not add Rust-only or unofficial parser fields as required metadata.
|
||||
|
||||
**Step 2: Check naming rules**
|
||||
|
||||
Ensure skill names are:
|
||||
- lowercase
|
||||
- hyphenated
|
||||
- stable
|
||||
|
||||
Names to keep:
|
||||
- `zhihu-navigate`
|
||||
- `zhihu-write`
|
||||
- `zhihu-hotlist`
|
||||
|
||||
**Step 3: Tighten descriptions**
|
||||
|
||||
Each description must:
|
||||
- begin with `Use when`
|
||||
- describe triggering conditions
|
||||
- mention Zhihu/browser context
|
||||
- avoid dumping full workflow detail
|
||||
|
||||
**Step 4: Validate frontmatter**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
rg -n "^name: |^description: |^version: |^author: |^tags:" /home/zyl/projects/sgClaw/skill_lib/skills/*/SKILL.md
|
||||
```
|
||||
|
||||
Expected: every skill emits the same five key families.
|
||||
|
||||
### Task 7: Add Repository-Level Verification Notes
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/zyl/projects/sgClaw/skill_lib/VERIFY.md`
|
||||
- Modify: `/home/zyl/projects/sgClaw/skill_lib/README.md`
|
||||
|
||||
**Step 1: Create `VERIFY.md`**
|
||||
|
||||
Document the manual verification checklist:
|
||||
- all skill packages are under `skill_lib/skills/`
|
||||
- each package has `SKILL.md`
|
||||
- long details live in `references/`
|
||||
- preserved source JSON is in `assets/`
|
||||
- no Rust source is copied into the skill repo
|
||||
|
||||
**Step 2: Link verification from the README**
|
||||
|
||||
Add a short section in `README.md` pointing to `VERIFY.md`.
|
||||
|
||||
**Step 3: Run repository-level checks**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
find /home/zyl/projects/sgClaw/skill_lib/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
|
||||
find /home/zyl/projects/sgClaw/skill_lib/skills -type d \( -name references -o -name assets \) | sort
|
||||
```
|
||||
|
||||
Expected:
|
||||
- exactly three `SKILL.md` files
|
||||
- each skill has `references/`
|
||||
- each skill has `assets/`
|
||||
|
||||
### Task 8: Final Review Before Claiming Completion
|
||||
|
||||
**Files:**
|
||||
- Review only: `/home/zyl/projects/sgClaw/skill_lib/`
|
||||
- Review only: `/home/zyl/projects/sgClaw/claw/docs/plans/2026-03-27-skill-lib-zeroclaw-plan.md`
|
||||
|
||||
**Step 1: Review against ZeroClaw runtime constraints**
|
||||
|
||||
Check that the final library respects the currently observed runtime facts:
|
||||
- directory-based skills
|
||||
- `SKILL.md` supported
|
||||
- simple frontmatter fields
|
||||
- optional `references/`, `scripts/`, `assets/`
|
||||
|
||||
**Step 2: Review against authoring quality**
|
||||
|
||||
Check that each skill:
|
||||
- is self-contained
|
||||
- has a narrow trigger boundary
|
||||
- avoids copying Rust internals into the prompt body
|
||||
- surfaces ambiguity and failure modes
|
||||
|
||||
**Step 3: Produce the implementation report**
|
||||
|
||||
The completion report must include:
|
||||
- created directories
|
||||
- created skill packages
|
||||
- any deliberate deviations from upstream ZeroClaw examples
|
||||
- verification commands actually run
|
||||
- unresolved risks
|
||||
|
||||
**Step 4: Stop before unrelated expansion**
|
||||
|
||||
Do not add:
|
||||
- extra skills beyond the three mapped ones
|
||||
- generic utility libraries
|
||||
- unrelated automation scripts
|
||||
- runtime code changes in `/home/zyl/projects/sgClaw/claw/src/skill/`
|
||||
|
||||
Reference in New Issue
Block a user