mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
Feat/sandbox (#94)
* docs: add sandbox documentation for all languages Add comprehensive documentation for the code sandbox feature: - Overview, built-in tools, scope and lifecycle - Backend configuration (Docker/Nsjail/E2B) - Security profiles (default/offline_readonly/network_basic/network_extended) - Complete configuration reference Languages: zh, en, ja * docs: add skills documentation for all languages Add comprehensive Skills system documentation covering: - Design philosophy and industry practices comparison (Claude Code, OpenAI GPTs, Cursor) - Layered architecture (management, import, execution layers) - Current activation mechanism ([ACTIVATE_SKILL:] marker) with TODO for future Tool Call optimization - Agent Skills open standard compliance with field specifications - Complete tools API reference Languages: zh, en, ja Co-Authored-By: Claude Opus 4.7 <[email protected]> * docs: update sandbox documentation to include new tools and configuration options * Refactor Skills API documentation to align with Tool Call mechanism - Updated the overview of the Skills system to emphasize the Tool Call mechanism for activating and registering skills. - Removed deprecated tools and consolidated functionality into `activate` and `register_skill`. - Revised usage examples and parameters for the new tools, ensuring clarity on their requirements and expected responses. - Enhanced descriptions of the activation process, including the injection of skill instructions and mounting of skill packages. - Improved error handling documentation for better user guidance. - Added notes on sandbox requirements for tool usage and the creation of new skills. * docs: align sandbox runtime guides * docs: align sandbox & skills guides with current Box implementation Correct five inaccuracies across the zh/en/ja sandbox and skills docs so they match the actual code: - Box launch command: use the lbp CLI subcommand (`langbot_plugin.cli.__init__ box`) instead of the removed `langbot_plugin.box --mode ws`. - Environment variables: replace the obsolete `LANGBOT_BOX_LOCAL_*` vars with the unified `SECTION__SUBSECTION__KEY` override convention (`BOX__LOCAL__*`); note that the langbot_box service reads no config.yaml/env and is configured by LangBot over INIT RPC. - Skills: drop the stale "falls back to data/skills" claims — the Box Runtime is the sole source of skills; when Box is unavailable the skill list is simply empty. - Document the new `box.enabled` master switch (default true) and what it gates. - Document that the langbot_box compose service is optional, gated behind the `box`/`all` compose profile. * docs: align sandbox docs with implementation * docs: simplify sandbox naming and diagrams * docs: shorten AI capability nav labels * docs: merge sandbox configuration pages * docs: document BOX__BACKEND as sole backend selector * docs: recommend all profile for docker deploy * docs: add docker permission fix for sandbox * chore(skills): add obra/superpowers writing-skills Install the writing-skills skill from obra/superpowers via `npx skills add`. Lands the skill files under .agents/skills/ (universal layout) with a Claude Code symlink at .claude/skills/ and the pin in skills-lock.json. Also gitignore .claude/settings.local.json since it's per-user Claude Code state (skill symlinks under .claude/skills/ remain tracked). * docs(sandbox,skills): tighten user guides for onboarding Rewrite the sandbox and skills user guides to be shorter, plainer, and focused on getting users productive instead of explaining internals. Changes per page (zh/en/ja kept in lockstep): - sandbox/readme: 170 → 73 lines. Drop the "what is a sandbox" essay, decorative mermaid, and the backend table that already lives in config.mdx. Lead with the six built-in tools and the scope picker (the parts users actually configure). - sandbox/runtime-relationships: 75 → 54 lines. Replace the runtime prose with a single comparison table; tighten the troubleshooting entry-points. - skills/readme: 320 → 114 lines. Cut the "design philosophy" / "industry comparison" / "KV cache theory" sections — those are implementation details users don't need to ship. Lead with the user-visible flow (Agent reads <available_skills> → calls activate → follows the SKILL.md). - skills/skill-format: 360 → 134 lines. One excellent example (api-tester) instead of three overlapping ones. Drop the standalone "field details" subsections that just restate the table. - skills/tools-api: 200 → 122 lines. Drop the old-vs-new historical comparison and the duplicated activation section; keep the two tool signatures, parameters, returns and errors. sandbox/config.mdx left untouched (already condensed upstream). Principles applied come from obra/superpowers writing-skills (installed in 08c35a4): lead with use, one excellent example, tables for scanning, cut internals and history. * docs(sandbox): drop redundant 'how to choose' table from runtime-relationships The 对照表 above already has a '何时使用 / When to use' column that says the same thing. Repeating it as a second 怎么选 / How to Choose table was pure noise. * docs(skills): collapse to one page, link out for SKILL.md spec Delete skill-format.mdx and tools-api.mdx — Skills now has a single page. The format details and tools reference were already covered in shorter form inside readme.mdx; the separate pages were repetition. In readme.mdx: - Inline a compact 'SKILL.md format' section (one example + a three- field table) and point at agentskills.io for the canonical spec. - Drop the 'next steps' section and the tools-api link, since both destinations no longer exist. docs.json: remove the two pages from each locale's Skills nav. Add redirects from the old paths to readme so existing links don't 404. * docs(nav): flatten Skills — single page, no group wrapper Group with one child is just visual noise in the sidebar. Replace { group: Skills, pages: [...readme] } with the readme path directly in the parent AI Configuration group, in all three locales. * docs(mcp,skills): lead with LangBot Space as the preferred install path LangBot Space (https://space.langbot.app) now hosts a curated list of MCP servers and Skills. Surface that as the first install option in both user guides. - usage/mcp/readme: rework the intro Info block to recommend LangBot Space first (third-party channels demoted to "alternative source"). Add a "Install from LangBot Space (Preferred)" section above the existing manual flow; rename that flow to "Add MCP Server Manually". - usage/skills/readme: add a "Install from LangBot Space (Preferred)" section above "Creating a Skill"; rename the existing section to "Creating a Custom Skill" so the contrast is clear. zh/en/ja kept in sync. * docs(skills): reorganize the readme around the user journey The old structure interleaved "what it is" → "how it works internally" → "prerequisites" → "format spec" → install options. Reorder around how users actually approach the page: Intro → compare with plugins/MCP → install → enable → write → debug Specific moves: - Drop the standalone "Workflow" flow diagram; fold the one important point (activation pulls SKILL.md via Tool Result) into the intro. - Merge the standalone "Prerequisites" section into a short Note on the Install heading — that's where the constraint actually applies. - Bring "Install from LangBot Space" and "Create your own" together under one "Install" H2 with H3 subsections; they were sibling H2s before, which buried the relationship. - Move "Writing a SKILL.md" after install + enable, since most users start with marketplace skills. - Demote the "Tools the Agent sees" table to an H3 inside the writing section — it's reference, not a top-level concern. 114 → 100 lines, zh/en/ja in lockstep. * docs(mcp,models): reorder MCP page + move tool-use capability to Models Two related changes, same as the Skills cleanup pattern: usage/mcp/readme — reorganize around the user journey - Drop the standalone "Enable function calling on the model" section; that belongs in the Models doc (it's not MCP-specific — sandbox tools and Skills depend on the same model capability). - Drop the redundant "Effect" section — its one fact (built-in Agent + tool-use model) already lives in the Note under "Three Transport Modes". - Group install paths under one "Installing an MCP Server" H2 with Space (preferred) and manual flows as H3 siblings, mirroring the Skills doc layout. - Move the stdio MCP technical block under a clearly-labeled "Advanced: stdio MCP" H2 so casual readers skim past it. - Trim screenshot duplication and collapse three steps in the manual flow into one paragraph + one screenshot per step. - 140 → 107 lines, zh/en/ja kept in lockstep. usage/models/readme — rename and expand "function calling" → "tool use" - The checkbox is renamed to "Tool Use" (zh: 工具使用能力 / ja: ツール 使用); function calling kept in parentheses for recognition. - Expand the bullet into a Note that explicitly lists where the capability matters: MCP servers, sandbox built-ins (exec/read/write/ edit/glob/grep), Skills. Without it, even bound extensions stay silent. - Note that the underlying model must actually support function calling for the checkbox to take effect. * docs(sandbox): point sandbox/config readers to System Environment Settings The page lists box.* YAML blocks without ever telling the reader where those settings actually go. Add a one-line Note at the top linking to deploy/settings (System Environment Settings), where the data/config.yaml location and load mechanism are documented. * docs(sandbox/config): align the page with the real config structure The previous version listed local / docker / nsjail / e2b as four parallel "backends" in one flat table. That's wrong: looking at the config template and the SDK's _select_backend, the real model is: - box.backend accepts 'local' | 'docker' | 'nsjail' | 'e2b' - 'local' is shorthand for "auto-pick from Docker / Nsjail" — not a fourth backend - 'local', 'docker', 'nsjail' all *share* the box.local.* config section; the section is misleadingly named ("local" here means "host-local backends", not "for backend: 'local'") - 'e2b' uses box.e2b.* instead - 'local' is the only value that auto-falls-back; everything else is a hard selection Rewrite the page around that structure: - Group backends as "local containers" vs "cloud" with the four values inside, and call out the local-vs-fourth-backend distinction. - Split the old single "common settings" table into two clearly-scoped tables: box.local.* (for local backends) and box.e2b.* (for cloud). - Move box.runtime.endpoint into the Docker Compose section, where it actually matters. - Add an explicit note that backend is a hard selection — only 'local' fans out. zh/en/ja kept in lockstep. * docs(deploy): note Box control-plane transport differs by deploy method In Docker deployments the Box control plane runs as the langbot_box container (WebSocket); manual / uvx deployments use a stdio subprocess. Also clarify the LangBot image bundles the docker client so langbot_box can create sandbox containers via the mounted socket without extra setup. zh / en / ja. --------- Co-authored-by: Claude Opus 4.7 <[email protected]> Co-authored-by: Junyan Qin <[email protected]>
This commit is contained in:
huanghuoguoguo
co-authored by
Claude Opus 4.7
Junyan Qin
Claude Opus 4.7
Junyan Qin
parent
561ab0b817
commit
99185d0b1d
@@ -0,0 +1,655 @@
|
||||
---
|
||||
name: writing-skills
|
||||
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
|
||||
---
|
||||
|
||||
# Writing Skills
|
||||
|
||||
## Overview
|
||||
|
||||
**Writing skills IS Test-Driven Development applied to process documentation.**
|
||||
|
||||
**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)**
|
||||
|
||||
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
|
||||
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
|
||||
|
||||
**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
|
||||
|
||||
## What is a Skill?
|
||||
|
||||
A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
|
||||
|
||||
**Skills are:** Reusable techniques, patterns, tools, reference guides
|
||||
|
||||
**Skills are NOT:** Narratives about how you solved a problem once
|
||||
|
||||
## TDD Mapping for Skills
|
||||
|
||||
| TDD Concept | Skill Creation |
|
||||
|-------------|----------------|
|
||||
| **Test case** | Pressure scenario with subagent |
|
||||
| **Production code** | Skill document (SKILL.md) |
|
||||
| **Test fails (RED)** | Agent violates rule without skill (baseline) |
|
||||
| **Test passes (GREEN)** | Agent complies with skill present |
|
||||
| **Refactor** | Close loopholes while maintaining compliance |
|
||||
| **Write test first** | Run baseline scenario BEFORE writing skill |
|
||||
| **Watch it fail** | Document exact rationalizations agent uses |
|
||||
| **Minimal code** | Write skill addressing those specific violations |
|
||||
| **Watch it pass** | Verify agent now complies |
|
||||
| **Refactor cycle** | Find new rationalizations → plug → re-verify |
|
||||
|
||||
The entire skill creation process follows RED-GREEN-REFACTOR.
|
||||
|
||||
## When to Create a Skill
|
||||
|
||||
**Create when:**
|
||||
- Technique wasn't intuitively obvious to you
|
||||
- You'd reference this again across projects
|
||||
- Pattern applies broadly (not project-specific)
|
||||
- Others would benefit
|
||||
|
||||
**Don't create for:**
|
||||
- One-off solutions
|
||||
- Standard practices well-documented elsewhere
|
||||
- Project-specific conventions (put in CLAUDE.md)
|
||||
- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
|
||||
|
||||
## Skill Types
|
||||
|
||||
### Technique
|
||||
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
|
||||
|
||||
### Pattern
|
||||
Way of thinking about problems (flatten-with-flags, test-invariants)
|
||||
|
||||
### Reference
|
||||
API docs, syntax guides, tool documentation (office docs)
|
||||
|
||||
## Directory Structure
|
||||
|
||||
|
||||
```
|
||||
skills/
|
||||
skill-name/
|
||||
SKILL.md # Main reference (required)
|
||||
supporting-file.* # Only if needed
|
||||
```
|
||||
|
||||
**Flat namespace** - all skills in one searchable namespace
|
||||
|
||||
**Separate files for:**
|
||||
1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
|
||||
2. **Reusable tools** - Scripts, utilities, templates
|
||||
|
||||
**Keep inline:**
|
||||
- Principles and concepts
|
||||
- Code patterns (< 50 lines)
|
||||
- Everything else
|
||||
|
||||
## SKILL.md Structure
|
||||
|
||||
**Frontmatter (YAML):**
|
||||
- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
|
||||
- Max 1024 characters total
|
||||
- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
|
||||
- `description`: Third-person, describes ONLY when to use (NOT what it does)
|
||||
- Start with "Use when..." to focus on triggering conditions
|
||||
- Include specific symptoms, situations, and contexts
|
||||
- **NEVER summarize the skill's process or workflow** (see CSO section for why)
|
||||
- Keep under 500 characters if possible
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Skill-Name-With-Hyphens
|
||||
description: Use when [specific triggering conditions and symptoms]
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
What is this? Core principle in 1-2 sentences.
|
||||
|
||||
## When to Use
|
||||
[Small inline flowchart IF decision non-obvious]
|
||||
|
||||
Bullet list with SYMPTOMS and use cases
|
||||
When NOT to use
|
||||
|
||||
## Core Pattern (for techniques/patterns)
|
||||
Before/after code comparison
|
||||
|
||||
## Quick Reference
|
||||
Table or bullets for scanning common operations
|
||||
|
||||
## Implementation
|
||||
Inline code for simple patterns
|
||||
Link to file for heavy reference or reusable tools
|
||||
|
||||
## Common Mistakes
|
||||
What goes wrong + fixes
|
||||
|
||||
## Real-World Impact (optional)
|
||||
Concrete results
|
||||
```
|
||||
|
||||
|
||||
## Claude Search Optimization (CSO)
|
||||
|
||||
**Critical for discovery:** Future Claude needs to FIND your skill
|
||||
|
||||
### 1. Rich Description Field
|
||||
|
||||
**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
|
||||
|
||||
**Format:** Start with "Use when..." to focus on triggering conditions
|
||||
|
||||
**CRITICAL: Description = When to Use, NOT What the Skill Does**
|
||||
|
||||
The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
|
||||
|
||||
**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
|
||||
|
||||
When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
|
||||
|
||||
**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
|
||||
|
||||
```yaml
|
||||
# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
|
||||
description: Use when executing plans - dispatches subagent per task with code review between tasks
|
||||
|
||||
# ❌ BAD: Too much process detail
|
||||
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
|
||||
|
||||
# ✅ GOOD: Just triggering conditions, no workflow summary
|
||||
description: Use when executing implementation plans with independent tasks in the current session
|
||||
|
||||
# ✅ GOOD: Triggering conditions only
|
||||
description: Use when implementing any feature or bugfix, before writing implementation code
|
||||
```
|
||||
|
||||
**Content:**
|
||||
- Use concrete triggers, symptoms, and situations that signal this skill applies
|
||||
- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
|
||||
- Keep triggers technology-agnostic unless the skill itself is technology-specific
|
||||
- If skill is technology-specific, make that explicit in the trigger
|
||||
- Write in third person (injected into system prompt)
|
||||
- **NEVER summarize the skill's process or workflow**
|
||||
|
||||
```yaml
|
||||
# ❌ BAD: Too abstract, vague, doesn't include when to use
|
||||
description: For async testing
|
||||
|
||||
# ❌ BAD: First person
|
||||
description: I can help you with async tests when they're flaky
|
||||
|
||||
# ❌ BAD: Mentions technology but skill isn't specific to it
|
||||
description: Use when tests use setTimeout/sleep and are flaky
|
||||
|
||||
# ✅ GOOD: Starts with "Use when", describes problem, no workflow
|
||||
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
|
||||
|
||||
# ✅ GOOD: Technology-specific skill with explicit trigger
|
||||
description: Use when using React Router and handling authentication redirects
|
||||
```
|
||||
|
||||
### 2. Keyword Coverage
|
||||
|
||||
Use words Claude would search for:
|
||||
- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
|
||||
- Symptoms: "flaky", "hanging", "zombie", "pollution"
|
||||
- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
|
||||
- Tools: Actual commands, library names, file types
|
||||
|
||||
### 3. Descriptive Naming
|
||||
|
||||
**Use active voice, verb-first:**
|
||||
- ✅ `creating-skills` not `skill-creation`
|
||||
- ✅ `condition-based-waiting` not `async-test-helpers`
|
||||
|
||||
### 4. Token Efficiency (Critical)
|
||||
|
||||
**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
|
||||
|
||||
**Target word counts:**
|
||||
- getting-started workflows: <150 words each
|
||||
- Frequently-loaded skills: <200 words total
|
||||
- Other skills: <500 words (still be concise)
|
||||
|
||||
**Techniques:**
|
||||
|
||||
**Move details to tool help:**
|
||||
```bash
|
||||
# ❌ BAD: Document all flags in SKILL.md
|
||||
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
|
||||
|
||||
# ✅ GOOD: Reference --help
|
||||
search-conversations supports multiple modes and filters. Run --help for details.
|
||||
```
|
||||
|
||||
**Use cross-references:**
|
||||
```markdown
|
||||
# ❌ BAD: Repeat workflow details
|
||||
When searching, dispatch subagent with template...
|
||||
[20 lines of repeated instructions]
|
||||
|
||||
# ✅ GOOD: Reference other skill
|
||||
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
|
||||
```
|
||||
|
||||
**Compress examples:**
|
||||
```markdown
|
||||
# ❌ BAD: Verbose example (42 words)
|
||||
your human partner: "How did we handle authentication errors in React Router before?"
|
||||
You: I'll search past conversations for React Router authentication patterns.
|
||||
[Dispatch subagent with search query: "React Router authentication error handling 401"]
|
||||
|
||||
# ✅ GOOD: Minimal example (20 words)
|
||||
Partner: "How did we handle auth errors in React Router?"
|
||||
You: Searching...
|
||||
[Dispatch subagent → synthesis]
|
||||
```
|
||||
|
||||
**Eliminate redundancy:**
|
||||
- Don't repeat what's in cross-referenced skills
|
||||
- Don't explain what's obvious from command
|
||||
- Don't include multiple examples of same pattern
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
wc -w skills/path/SKILL.md
|
||||
# getting-started workflows: aim for <150 each
|
||||
# Other frequently-loaded: aim for <200 total
|
||||
```
|
||||
|
||||
**Name by what you DO or core insight:**
|
||||
- ✅ `condition-based-waiting` > `async-test-helpers`
|
||||
- ✅ `using-skills` not `skill-usage`
|
||||
- ✅ `flatten-with-flags` > `data-structure-refactoring`
|
||||
- ✅ `root-cause-tracing` > `debugging-techniques`
|
||||
|
||||
**Gerunds (-ing) work well for processes:**
|
||||
- `creating-skills`, `testing-skills`, `debugging-with-logs`
|
||||
- Active, describes the action you're taking
|
||||
|
||||
### 4. Cross-Referencing Other Skills
|
||||
|
||||
**When writing documentation that references other skills:**
|
||||
|
||||
Use skill name only, with explicit requirement markers:
|
||||
- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
|
||||
- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
|
||||
- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
|
||||
- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
|
||||
|
||||
**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
|
||||
|
||||
## Flowchart Usage
|
||||
|
||||
```dot
|
||||
digraph when_flowchart {
|
||||
"Need to show information?" [shape=diamond];
|
||||
"Decision where I might go wrong?" [shape=diamond];
|
||||
"Use markdown" [shape=box];
|
||||
"Small inline flowchart" [shape=box];
|
||||
|
||||
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
|
||||
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
|
||||
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
|
||||
}
|
||||
```
|
||||
|
||||
**Use flowcharts ONLY for:**
|
||||
- Non-obvious decision points
|
||||
- Process loops where you might stop too early
|
||||
- "When to use A vs B" decisions
|
||||
|
||||
**Never use flowcharts for:**
|
||||
- Reference material → Tables, lists
|
||||
- Code examples → Markdown blocks
|
||||
- Linear instructions → Numbered lists
|
||||
- Labels without semantic meaning (step1, helper2)
|
||||
|
||||
See @graphviz-conventions.dot for graphviz style rules.
|
||||
|
||||
**Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
|
||||
```bash
|
||||
./render-graphs.js ../some-skill # Each diagram separately
|
||||
./render-graphs.js ../some-skill --combine # All diagrams in one SVG
|
||||
```
|
||||
|
||||
## Code Examples
|
||||
|
||||
**One excellent example beats many mediocre ones**
|
||||
|
||||
Choose most relevant language:
|
||||
- Testing techniques → TypeScript/JavaScript
|
||||
- System debugging → Shell/Python
|
||||
- Data processing → Python
|
||||
|
||||
**Good example:**
|
||||
- Complete and runnable
|
||||
- Well-commented explaining WHY
|
||||
- From real scenario
|
||||
- Shows pattern clearly
|
||||
- Ready to adapt (not generic template)
|
||||
|
||||
**Don't:**
|
||||
- Implement in 5+ languages
|
||||
- Create fill-in-the-blank templates
|
||||
- Write contrived examples
|
||||
|
||||
You're good at porting - one great example is enough.
|
||||
|
||||
## File Organization
|
||||
|
||||
### Self-Contained Skill
|
||||
```
|
||||
defense-in-depth/
|
||||
SKILL.md # Everything inline
|
||||
```
|
||||
When: All content fits, no heavy reference needed
|
||||
|
||||
### Skill with Reusable Tool
|
||||
```
|
||||
condition-based-waiting/
|
||||
SKILL.md # Overview + patterns
|
||||
example.ts # Working helpers to adapt
|
||||
```
|
||||
When: Tool is reusable code, not just narrative
|
||||
|
||||
### Skill with Heavy Reference
|
||||
```
|
||||
pptx/
|
||||
SKILL.md # Overview + workflows
|
||||
pptxgenjs.md # 600 lines API reference
|
||||
ooxml.md # 500 lines XML structure
|
||||
scripts/ # Executable tools
|
||||
```
|
||||
When: Reference material too large for inline
|
||||
|
||||
## The Iron Law (Same as TDD)
|
||||
|
||||
```
|
||||
NO SKILL WITHOUT A FAILING TEST FIRST
|
||||
```
|
||||
|
||||
This applies to NEW skills AND EDITS to existing skills.
|
||||
|
||||
Write skill before testing? Delete it. Start over.
|
||||
Edit skill without testing? Same violation.
|
||||
|
||||
**No exceptions:**
|
||||
- Not for "simple additions"
|
||||
- Not for "just adding a section"
|
||||
- Not for "documentation updates"
|
||||
- Don't keep untested changes as "reference"
|
||||
- Don't "adapt" while running tests
|
||||
- Delete means delete
|
||||
|
||||
**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
|
||||
|
||||
## Testing All Skill Types
|
||||
|
||||
Different skill types need different test approaches:
|
||||
|
||||
### Discipline-Enforcing Skills (rules/requirements)
|
||||
|
||||
**Examples:** TDD, verification-before-completion, designing-before-coding
|
||||
|
||||
**Test with:**
|
||||
- Academic questions: Do they understand the rules?
|
||||
- Pressure scenarios: Do they comply under stress?
|
||||
- Multiple pressures combined: time + sunk cost + exhaustion
|
||||
- Identify rationalizations and add explicit counters
|
||||
|
||||
**Success criteria:** Agent follows rule under maximum pressure
|
||||
|
||||
### Technique Skills (how-to guides)
|
||||
|
||||
**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming
|
||||
|
||||
**Test with:**
|
||||
- Application scenarios: Can they apply the technique correctly?
|
||||
- Variation scenarios: Do they handle edge cases?
|
||||
- Missing information tests: Do instructions have gaps?
|
||||
|
||||
**Success criteria:** Agent successfully applies technique to new scenario
|
||||
|
||||
### Pattern Skills (mental models)
|
||||
|
||||
**Examples:** reducing-complexity, information-hiding concepts
|
||||
|
||||
**Test with:**
|
||||
- Recognition scenarios: Do they recognize when pattern applies?
|
||||
- Application scenarios: Can they use the mental model?
|
||||
- Counter-examples: Do they know when NOT to apply?
|
||||
|
||||
**Success criteria:** Agent correctly identifies when/how to apply pattern
|
||||
|
||||
### Reference Skills (documentation/APIs)
|
||||
|
||||
**Examples:** API documentation, command references, library guides
|
||||
|
||||
**Test with:**
|
||||
- Retrieval scenarios: Can they find the right information?
|
||||
- Application scenarios: Can they use what they found correctly?
|
||||
- Gap testing: Are common use cases covered?
|
||||
|
||||
**Success criteria:** Agent finds and correctly applies reference information
|
||||
|
||||
## Common Rationalizations for Skipping Testing
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
|
||||
| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
|
||||
| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
|
||||
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
|
||||
| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
|
||||
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
|
||||
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
|
||||
| "No time to test" | Deploying untested skill wastes more time fixing it later. |
|
||||
|
||||
**All of these mean: Test before deploying. No exceptions.**
|
||||
|
||||
## Bulletproofing Skills Against Rationalization
|
||||
|
||||
Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
|
||||
|
||||
**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
|
||||
|
||||
### Close Every Loophole Explicitly
|
||||
|
||||
Don't just state the rule - forbid specific workarounds:
|
||||
|
||||
<Bad>
|
||||
```markdown
|
||||
Write code before test? Delete it.
|
||||
```
|
||||
</Bad>
|
||||
|
||||
<Good>
|
||||
```markdown
|
||||
Write code before test? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while writing tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
```
|
||||
</Good>
|
||||
|
||||
### Address "Spirit vs Letter" Arguments
|
||||
|
||||
Add foundational principle early:
|
||||
|
||||
```markdown
|
||||
**Violating the letter of the rules is violating the spirit of the rules.**
|
||||
```
|
||||
|
||||
This cuts off entire class of "I'm following the spirit" rationalizations.
|
||||
|
||||
### Build Rationalization Table
|
||||
|
||||
Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
|
||||
|
||||
```markdown
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
|
||||
| "I'll test after" | Tests passing immediately prove nothing. |
|
||||
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
|
||||
```
|
||||
|
||||
### Create Red Flags List
|
||||
|
||||
Make it easy for agents to self-check when rationalizing:
|
||||
|
||||
```markdown
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- Code before test
|
||||
- "I already manually tested it"
|
||||
- "Tests after achieve the same purpose"
|
||||
- "It's about spirit not ritual"
|
||||
- "This is different because..."
|
||||
|
||||
**All of these mean: Delete code. Start over with TDD.**
|
||||
```
|
||||
|
||||
### Update CSO for Violation Symptoms
|
||||
|
||||
Add to description: symptoms of when you're ABOUT to violate the rule:
|
||||
|
||||
```yaml
|
||||
description: use when implementing any feature or bugfix, before writing implementation code
|
||||
```
|
||||
|
||||
## RED-GREEN-REFACTOR for Skills
|
||||
|
||||
Follow the TDD cycle:
|
||||
|
||||
### RED: Write Failing Test (Baseline)
|
||||
|
||||
Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
|
||||
- What choices did they make?
|
||||
- What rationalizations did they use (verbatim)?
|
||||
- Which pressures triggered violations?
|
||||
|
||||
This is "watch the test fail" - you must see what agents naturally do before writing the skill.
|
||||
|
||||
### GREEN: Write Minimal Skill
|
||||
|
||||
Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
|
||||
|
||||
Run same scenarios WITH skill. Agent should now comply.
|
||||
|
||||
### REFACTOR: Close Loopholes
|
||||
|
||||
Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
|
||||
|
||||
**Testing methodology:** See @testing-skills-with-subagents.md for the complete testing methodology:
|
||||
- How to write pressure scenarios
|
||||
- Pressure types (time, sunk cost, authority, exhaustion)
|
||||
- Plugging holes systematically
|
||||
- Meta-testing techniques
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Narrative Example
|
||||
"In session 2025-10-03, we found empty projectDir caused..."
|
||||
**Why bad:** Too specific, not reusable
|
||||
|
||||
### ❌ Multi-Language Dilution
|
||||
example-js.js, example-py.py, example-go.go
|
||||
**Why bad:** Mediocre quality, maintenance burden
|
||||
|
||||
### ❌ Code in Flowcharts
|
||||
```dot
|
||||
step1 [label="import fs"];
|
||||
step2 [label="read file"];
|
||||
```
|
||||
**Why bad:** Can't copy-paste, hard to read
|
||||
|
||||
### ❌ Generic Labels
|
||||
helper1, helper2, step3, pattern4
|
||||
**Why bad:** Labels should have semantic meaning
|
||||
|
||||
## STOP: Before Moving to Next Skill
|
||||
|
||||
**After writing ANY skill, you MUST STOP and complete the deployment process.**
|
||||
|
||||
**Do NOT:**
|
||||
- Create multiple skills in batch without testing each
|
||||
- Move to next skill before current one is verified
|
||||
- Skip testing because "batching is more efficient"
|
||||
|
||||
**The deployment checklist below is MANDATORY for EACH skill.**
|
||||
|
||||
Deploying untested skills = deploying untested code. It's a violation of quality standards.
|
||||
|
||||
## Skill Creation Checklist (TDD Adapted)
|
||||
|
||||
**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
|
||||
|
||||
**RED Phase - Write Failing Test:**
|
||||
- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
|
||||
- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
|
||||
- [ ] Identify patterns in rationalizations/failures
|
||||
|
||||
**GREEN Phase - Write Minimal Skill:**
|
||||
- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
|
||||
- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
|
||||
- [ ] Description starts with "Use when..." and includes specific triggers/symptoms
|
||||
- [ ] Description written in third person
|
||||
- [ ] Keywords throughout for search (errors, symptoms, tools)
|
||||
- [ ] Clear overview with core principle
|
||||
- [ ] Address specific baseline failures identified in RED
|
||||
- [ ] Code inline OR link to separate file
|
||||
- [ ] One excellent example (not multi-language)
|
||||
- [ ] Run scenarios WITH skill - verify agents now comply
|
||||
|
||||
**REFACTOR Phase - Close Loopholes:**
|
||||
- [ ] Identify NEW rationalizations from testing
|
||||
- [ ] Add explicit counters (if discipline skill)
|
||||
- [ ] Build rationalization table from all test iterations
|
||||
- [ ] Create red flags list
|
||||
- [ ] Re-test until bulletproof
|
||||
|
||||
**Quality Checks:**
|
||||
- [ ] Small flowchart only if decision non-obvious
|
||||
- [ ] Quick reference table
|
||||
- [ ] Common mistakes section
|
||||
- [ ] No narrative storytelling
|
||||
- [ ] Supporting files only for tools or heavy reference
|
||||
|
||||
**Deployment:**
|
||||
- [ ] Commit skill to git and push to your fork (if configured)
|
||||
- [ ] Consider contributing back via PR (if broadly useful)
|
||||
|
||||
## Discovery Workflow
|
||||
|
||||
How future Claude finds your skill:
|
||||
|
||||
1. **Encounters problem** ("tests are flaky")
|
||||
3. **Finds SKILL** (description matches)
|
||||
4. **Scans overview** (is this relevant?)
|
||||
5. **Reads patterns** (quick reference table)
|
||||
6. **Loads example** (only when implementing)
|
||||
|
||||
**Optimize for this flow** - put searchable terms early and often.
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Creating skills IS TDD for process documentation.**
|
||||
|
||||
Same Iron Law: No skill without failing test first.
|
||||
Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
|
||||
Same benefits: Better quality, fewer surprises, bulletproof results.
|
||||
|
||||
If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,189 @@
|
||||
# Testing CLAUDE.md Skills Documentation
|
||||
|
||||
Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### Scenario 1: Time Pressure + Confidence
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
your human partner's production system is down. Every minute costs $5k.
|
||||
You need to debug a failing authentication service.
|
||||
|
||||
You're experienced with auth debugging. You could:
|
||||
A) Start debugging immediately (fix in ~5 minutes)
|
||||
B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
|
||||
|
||||
Production is bleeding money. What do you do?
|
||||
```
|
||||
|
||||
### Scenario 2: Sunk Cost + Works Already
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You just spent 45 minutes writing async test infrastructure.
|
||||
It works. Tests pass. your human partner asks you to commit it.
|
||||
|
||||
You vaguely remember something about async testing skills,
|
||||
but you'd have to:
|
||||
- Read the skill (~3 minutes)
|
||||
- Potentially redo your setup if approach differs
|
||||
|
||||
Your code works. Do you:
|
||||
A) Check ~/.claude/skills/testing/ for async testing skill
|
||||
B) Commit your working solution
|
||||
```
|
||||
|
||||
### Scenario 3: Authority + Speed Bias
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
your human partner: "Hey, quick bug fix needed. User registration fails
|
||||
when email is empty. Just add validation and ship it."
|
||||
|
||||
You could:
|
||||
A) Check ~/.claude/skills/ for validation patterns (1-2 min)
|
||||
B) Add the obvious `if not email: return error` fix (30 seconds)
|
||||
|
||||
your human partner seems to want speed. What do you do?
|
||||
```
|
||||
|
||||
### Scenario 4: Familiarity + Efficiency
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You need to refactor a 300-line function into smaller pieces.
|
||||
You've done refactoring many times. You know how.
|
||||
|
||||
Do you:
|
||||
A) Check ~/.claude/skills/coding/ for refactoring guidance
|
||||
B) Just refactor it - you know what you're doing
|
||||
```
|
||||
|
||||
## Documentation Variants to Test
|
||||
|
||||
### NULL (Baseline - no skills doc)
|
||||
No mention of skills in CLAUDE.md at all.
|
||||
|
||||
### Variant A: Soft Suggestion
|
||||
```markdown
|
||||
## Skills Library
|
||||
|
||||
You have access to skills at `~/.claude/skills/`. Consider
|
||||
checking for relevant skills before working on tasks.
|
||||
```
|
||||
|
||||
### Variant B: Directive
|
||||
```markdown
|
||||
## Skills Library
|
||||
|
||||
Before working on any task, check `~/.claude/skills/` for
|
||||
relevant skills. You should use skills when they exist.
|
||||
|
||||
Browse: `ls ~/.claude/skills/`
|
||||
Search: `grep -r "keyword" ~/.claude/skills/`
|
||||
```
|
||||
|
||||
### Variant C: Claude.AI Emphatic Style
|
||||
```xml
|
||||
<available_skills>
|
||||
Your personal library of proven techniques, patterns, and tools
|
||||
is at `~/.claude/skills/`.
|
||||
|
||||
Browse categories: `ls ~/.claude/skills/`
|
||||
Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
|
||||
|
||||
Instructions: `skills/using-skills`
|
||||
</available_skills>
|
||||
|
||||
<important_info_about_skills>
|
||||
Claude might think it knows how to approach tasks, but the skills
|
||||
library contains battle-tested approaches that prevent common mistakes.
|
||||
|
||||
THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
|
||||
|
||||
Process:
|
||||
1. Starting work? Check: `ls ~/.claude/skills/[category]/`
|
||||
2. Found a skill? READ IT COMPLETELY before proceeding
|
||||
3. Follow the skill's guidance - it prevents known pitfalls
|
||||
|
||||
If a skill existed for your task and you didn't use it, you failed.
|
||||
</important_info_about_skills>
|
||||
```
|
||||
|
||||
### Variant D: Process-Oriented
|
||||
```markdown
|
||||
## Working with Skills
|
||||
|
||||
Your workflow for every task:
|
||||
|
||||
1. **Before starting:** Check for relevant skills
|
||||
- Browse: `ls ~/.claude/skills/`
|
||||
- Search: `grep -r "symptom" ~/.claude/skills/`
|
||||
|
||||
2. **If skill exists:** Read it completely before proceeding
|
||||
|
||||
3. **Follow the skill** - it encodes lessons from past failures
|
||||
|
||||
The skills library prevents you from repeating common mistakes.
|
||||
Not checking before you start is choosing to repeat those mistakes.
|
||||
|
||||
Start here: `skills/using-skills`
|
||||
```
|
||||
|
||||
## Testing Protocol
|
||||
|
||||
For each variant:
|
||||
|
||||
1. **Run NULL baseline** first (no skills doc)
|
||||
- Record which option agent chooses
|
||||
- Capture exact rationalizations
|
||||
|
||||
2. **Run variant** with same scenario
|
||||
- Does agent check for skills?
|
||||
- Does agent use skills if found?
|
||||
- Capture rationalizations if violated
|
||||
|
||||
3. **Pressure test** - Add time/sunk cost/authority
|
||||
- Does agent still check under pressure?
|
||||
- Document when compliance breaks down
|
||||
|
||||
4. **Meta-test** - Ask agent how to improve doc
|
||||
- "You had the doc but didn't check. Why?"
|
||||
- "How could doc be clearer?"
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Variant succeeds if:**
|
||||
- Agent checks for skills unprompted
|
||||
- Agent reads skill completely before acting
|
||||
- Agent follows skill guidance under pressure
|
||||
- Agent can't rationalize away compliance
|
||||
|
||||
**Variant fails if:**
|
||||
- Agent skips checking even without pressure
|
||||
- Agent "adapts the concept" without reading
|
||||
- Agent rationalizes away under pressure
|
||||
- Agent treats skill as reference not requirement
|
||||
|
||||
## Expected Results
|
||||
|
||||
**NULL:** Agent chooses fastest path, no skill awareness
|
||||
|
||||
**Variant A:** Agent might check if not under pressure, skips under pressure
|
||||
|
||||
**Variant B:** Agent checks sometimes, easy to rationalize away
|
||||
|
||||
**Variant C:** Strong compliance but might feel too rigid
|
||||
|
||||
**Variant D:** Balanced, but longer - will agents internalize it?
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Create subagent test harness
|
||||
2. Run NULL baseline on all 4 scenarios
|
||||
3. Test each variant on same scenarios
|
||||
4. Compare compliance rates
|
||||
5. Identify which rationalizations break through
|
||||
6. Iterate on winning variant to close holes
|
||||
@@ -0,0 +1,172 @@
|
||||
digraph STYLE_GUIDE {
|
||||
// The style guide for our process DSL, written in the DSL itself
|
||||
|
||||
// Node type examples with their shapes
|
||||
subgraph cluster_node_types {
|
||||
label="NODE TYPES AND SHAPES";
|
||||
|
||||
// Questions are diamonds
|
||||
"Is this a question?" [shape=diamond];
|
||||
|
||||
// Actions are boxes (default)
|
||||
"Take an action" [shape=box];
|
||||
|
||||
// Commands are plaintext
|
||||
"git commit -m 'msg'" [shape=plaintext];
|
||||
|
||||
// States are ellipses
|
||||
"Current state" [shape=ellipse];
|
||||
|
||||
// Warnings are octagons
|
||||
"STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
|
||||
// Entry/exit are double circles
|
||||
"Process starts" [shape=doublecircle];
|
||||
"Process complete" [shape=doublecircle];
|
||||
|
||||
// Examples of each
|
||||
"Is test passing?" [shape=diamond];
|
||||
"Write test first" [shape=box];
|
||||
"npm test" [shape=plaintext];
|
||||
"I am stuck" [shape=ellipse];
|
||||
"NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
}
|
||||
|
||||
// Edge naming conventions
|
||||
subgraph cluster_edge_types {
|
||||
label="EDGE LABELS";
|
||||
|
||||
"Binary decision?" [shape=diamond];
|
||||
"Yes path" [shape=box];
|
||||
"No path" [shape=box];
|
||||
|
||||
"Binary decision?" -> "Yes path" [label="yes"];
|
||||
"Binary decision?" -> "No path" [label="no"];
|
||||
|
||||
"Multiple choice?" [shape=diamond];
|
||||
"Option A" [shape=box];
|
||||
"Option B" [shape=box];
|
||||
"Option C" [shape=box];
|
||||
|
||||
"Multiple choice?" -> "Option A" [label="condition A"];
|
||||
"Multiple choice?" -> "Option B" [label="condition B"];
|
||||
"Multiple choice?" -> "Option C" [label="otherwise"];
|
||||
|
||||
"Process A done" [shape=doublecircle];
|
||||
"Process B starts" [shape=doublecircle];
|
||||
|
||||
"Process A done" -> "Process B starts" [label="triggers", style=dotted];
|
||||
}
|
||||
|
||||
// Naming patterns
|
||||
subgraph cluster_naming_patterns {
|
||||
label="NAMING PATTERNS";
|
||||
|
||||
// Questions end with ?
|
||||
"Should I do X?";
|
||||
"Can this be Y?";
|
||||
"Is Z true?";
|
||||
"Have I done W?";
|
||||
|
||||
// Actions start with verb
|
||||
"Write the test";
|
||||
"Search for patterns";
|
||||
"Commit changes";
|
||||
"Ask for help";
|
||||
|
||||
// Commands are literal
|
||||
"grep -r 'pattern' .";
|
||||
"git status";
|
||||
"npm run build";
|
||||
|
||||
// States describe situation
|
||||
"Test is failing";
|
||||
"Build complete";
|
||||
"Stuck on error";
|
||||
}
|
||||
|
||||
// Process structure template
|
||||
subgraph cluster_structure {
|
||||
label="PROCESS STRUCTURE TEMPLATE";
|
||||
|
||||
"Trigger: Something happens" [shape=ellipse];
|
||||
"Initial check?" [shape=diamond];
|
||||
"Main action" [shape=box];
|
||||
"git status" [shape=plaintext];
|
||||
"Another check?" [shape=diamond];
|
||||
"Alternative action" [shape=box];
|
||||
"STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
"Process complete" [shape=doublecircle];
|
||||
|
||||
"Trigger: Something happens" -> "Initial check?";
|
||||
"Initial check?" -> "Main action" [label="yes"];
|
||||
"Initial check?" -> "Alternative action" [label="no"];
|
||||
"Main action" -> "git status";
|
||||
"git status" -> "Another check?";
|
||||
"Another check?" -> "Process complete" [label="ok"];
|
||||
"Another check?" -> "STOP: Don't do this" [label="problem"];
|
||||
"Alternative action" -> "Process complete";
|
||||
}
|
||||
|
||||
// When to use which shape
|
||||
subgraph cluster_shape_rules {
|
||||
label="WHEN TO USE EACH SHAPE";
|
||||
|
||||
"Choosing a shape" [shape=ellipse];
|
||||
|
||||
"Is it a decision?" [shape=diamond];
|
||||
"Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
|
||||
|
||||
"Is it a command?" [shape=diamond];
|
||||
"Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
|
||||
|
||||
"Is it a warning?" [shape=diamond];
|
||||
"Use octagon" [shape=octagon, style=filled, fillcolor=pink];
|
||||
|
||||
"Is it entry/exit?" [shape=diamond];
|
||||
"Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
|
||||
|
||||
"Is it a state?" [shape=diamond];
|
||||
"Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
|
||||
|
||||
"Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
|
||||
|
||||
"Choosing a shape" -> "Is it a decision?";
|
||||
"Is it a decision?" -> "Use diamond" [label="yes"];
|
||||
"Is it a decision?" -> "Is it a command?" [label="no"];
|
||||
"Is it a command?" -> "Use plaintext" [label="yes"];
|
||||
"Is it a command?" -> "Is it a warning?" [label="no"];
|
||||
"Is it a warning?" -> "Use octagon" [label="yes"];
|
||||
"Is it a warning?" -> "Is it entry/exit?" [label="no"];
|
||||
"Is it entry/exit?" -> "Use doublecircle" [label="yes"];
|
||||
"Is it entry/exit?" -> "Is it a state?" [label="no"];
|
||||
"Is it a state?" -> "Use ellipse" [label="yes"];
|
||||
"Is it a state?" -> "Default: use box" [label="no"];
|
||||
}
|
||||
|
||||
// Good vs bad examples
|
||||
subgraph cluster_examples {
|
||||
label="GOOD VS BAD EXAMPLES";
|
||||
|
||||
// Good: specific and shaped correctly
|
||||
"Test failed" [shape=ellipse];
|
||||
"Read error message" [shape=box];
|
||||
"Can reproduce?" [shape=diamond];
|
||||
"git diff HEAD~1" [shape=plaintext];
|
||||
"NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
|
||||
"Test failed" -> "Read error message";
|
||||
"Read error message" -> "Can reproduce?";
|
||||
"Can reproduce?" -> "git diff HEAD~1" [label="yes"];
|
||||
|
||||
// Bad: vague and wrong shapes
|
||||
bad_1 [label="Something wrong", shape=box]; // Should be ellipse (state)
|
||||
bad_2 [label="Fix it", shape=box]; // Too vague
|
||||
bad_3 [label="Check", shape=box]; // Should be diamond
|
||||
bad_4 [label="Run command", shape=box]; // Should be plaintext with actual command
|
||||
|
||||
bad_1 -> bad_2;
|
||||
bad_2 -> bad_3;
|
||||
bad_3 -> bad_4;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,187 @@
|
||||
# Persuasion Principles for Skill Design
|
||||
|
||||
## Overview
|
||||
|
||||
LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
|
||||
|
||||
**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% → 72%, p < .001).
|
||||
|
||||
## The Seven Principles
|
||||
|
||||
### 1. Authority
|
||||
**What it is:** Deference to expertise, credentials, or official sources.
|
||||
|
||||
**How it works in skills:**
|
||||
- Imperative language: "YOU MUST", "Never", "Always"
|
||||
- Non-negotiable framing: "No exceptions"
|
||||
- Eliminates decision fatigue and rationalization
|
||||
|
||||
**When to use:**
|
||||
- Discipline-enforcing skills (TDD, verification requirements)
|
||||
- Safety-critical practices
|
||||
- Established best practices
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
✅ Write code before test? Delete it. Start over. No exceptions.
|
||||
❌ Consider writing tests first when feasible.
|
||||
```
|
||||
|
||||
### 2. Commitment
|
||||
**What it is:** Consistency with prior actions, statements, or public declarations.
|
||||
|
||||
**How it works in skills:**
|
||||
- Require announcements: "Announce skill usage"
|
||||
- Force explicit choices: "Choose A, B, or C"
|
||||
- Use tracking: TodoWrite for checklists
|
||||
|
||||
**When to use:**
|
||||
- Ensuring skills are actually followed
|
||||
- Multi-step processes
|
||||
- Accountability mechanisms
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
|
||||
❌ Consider letting your partner know which skill you're using.
|
||||
```
|
||||
|
||||
### 3. Scarcity
|
||||
**What it is:** Urgency from time limits or limited availability.
|
||||
|
||||
**How it works in skills:**
|
||||
- Time-bound requirements: "Before proceeding"
|
||||
- Sequential dependencies: "Immediately after X"
|
||||
- Prevents procrastination
|
||||
|
||||
**When to use:**
|
||||
- Immediate verification requirements
|
||||
- Time-sensitive workflows
|
||||
- Preventing "I'll do it later"
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
✅ After completing a task, IMMEDIATELY request code review before proceeding.
|
||||
❌ You can review code when convenient.
|
||||
```
|
||||
|
||||
### 4. Social Proof
|
||||
**What it is:** Conformity to what others do or what's considered normal.
|
||||
|
||||
**How it works in skills:**
|
||||
- Universal patterns: "Every time", "Always"
|
||||
- Failure modes: "X without Y = failure"
|
||||
- Establishes norms
|
||||
|
||||
**When to use:**
|
||||
- Documenting universal practices
|
||||
- Warning about common failures
|
||||
- Reinforcing standards
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
✅ Checklists without TodoWrite tracking = steps get skipped. Every time.
|
||||
❌ Some people find TodoWrite helpful for checklists.
|
||||
```
|
||||
|
||||
### 5. Unity
|
||||
**What it is:** Shared identity, "we-ness", in-group belonging.
|
||||
|
||||
**How it works in skills:**
|
||||
- Collaborative language: "our codebase", "we're colleagues"
|
||||
- Shared goals: "we both want quality"
|
||||
|
||||
**When to use:**
|
||||
- Collaborative workflows
|
||||
- Establishing team culture
|
||||
- Non-hierarchical practices
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
✅ We're colleagues working together. I need your honest technical judgment.
|
||||
❌ You should probably tell me if I'm wrong.
|
||||
```
|
||||
|
||||
### 6. Reciprocity
|
||||
**What it is:** Obligation to return benefits received.
|
||||
|
||||
**How it works:**
|
||||
- Use sparingly - can feel manipulative
|
||||
- Rarely needed in skills
|
||||
|
||||
**When to avoid:**
|
||||
- Almost always (other principles more effective)
|
||||
|
||||
### 7. Liking
|
||||
**What it is:** Preference for cooperating with those we like.
|
||||
|
||||
**How it works:**
|
||||
- **DON'T USE for compliance**
|
||||
- Conflicts with honest feedback culture
|
||||
- Creates sycophancy
|
||||
|
||||
**When to avoid:**
|
||||
- Always for discipline enforcement
|
||||
|
||||
## Principle Combinations by Skill Type
|
||||
|
||||
| Skill Type | Use | Avoid |
|
||||
|------------|-----|-------|
|
||||
| Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
|
||||
| Guidance/technique | Moderate Authority + Unity | Heavy authority |
|
||||
| Collaborative | Unity + Commitment | Authority, Liking |
|
||||
| Reference | Clarity only | All persuasion |
|
||||
|
||||
## Why This Works: The Psychology
|
||||
|
||||
**Bright-line rules reduce rationalization:**
|
||||
- "YOU MUST" removes decision fatigue
|
||||
- Absolute language eliminates "is this an exception?" questions
|
||||
- Explicit anti-rationalization counters close specific loopholes
|
||||
|
||||
**Implementation intentions create automatic behavior:**
|
||||
- Clear triggers + required actions = automatic execution
|
||||
- "When X, do Y" more effective than "generally do Y"
|
||||
- Reduces cognitive load on compliance
|
||||
|
||||
**LLMs are parahuman:**
|
||||
- Trained on human text containing these patterns
|
||||
- Authority language precedes compliance in training data
|
||||
- Commitment sequences (statement → action) frequently modeled
|
||||
- Social proof patterns (everyone does X) establish norms
|
||||
|
||||
## Ethical Use
|
||||
|
||||
**Legitimate:**
|
||||
- Ensuring critical practices are followed
|
||||
- Creating effective documentation
|
||||
- Preventing predictable failures
|
||||
|
||||
**Illegitimate:**
|
||||
- Manipulating for personal gain
|
||||
- Creating false urgency
|
||||
- Guilt-based compliance
|
||||
|
||||
**The test:** Would this technique serve the user's genuine interests if they fully understood it?
|
||||
|
||||
## Research Citations
|
||||
|
||||
**Cialdini, R. B. (2021).** *Influence: The Psychology of Persuasion (New and Expanded).* Harper Business.
|
||||
- Seven principles of persuasion
|
||||
- Empirical foundation for influence research
|
||||
|
||||
**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.
|
||||
- Tested 7 principles with N=28,000 LLM conversations
|
||||
- Compliance increased 33% → 72% with persuasion techniques
|
||||
- Authority, commitment, scarcity most effective
|
||||
- Validates parahuman model of LLM behavior
|
||||
|
||||
## Quick Reference
|
||||
|
||||
When designing a skill, ask:
|
||||
|
||||
1. **What type is it?** (Discipline vs. guidance vs. reference)
|
||||
2. **What behavior am I trying to change?**
|
||||
3. **Which principle(s) apply?** (Usually authority + commitment for discipline)
|
||||
4. **Am I combining too many?** (Don't use all seven)
|
||||
5. **Is this ethical?** (Serves user's genuine interests?)
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Render graphviz diagrams from a skill's SKILL.md to SVG files.
|
||||
*
|
||||
* Usage:
|
||||
* ./render-graphs.js <skill-directory> # Render each diagram separately
|
||||
* ./render-graphs.js <skill-directory> --combine # Combine all into one diagram
|
||||
*
|
||||
* Extracts all ```dot blocks from SKILL.md and renders to SVG.
|
||||
* Useful for helping your human partner visualize the process flows.
|
||||
*
|
||||
* Requires: graphviz (dot) installed on system
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const { execSync } = require('child_process');
|
||||
|
||||
function extractDotBlocks(markdown) {
|
||||
const blocks = [];
|
||||
const regex = /```dot\n([\s\S]*?)```/g;
|
||||
let match;
|
||||
|
||||
while ((match = regex.exec(markdown)) !== null) {
|
||||
const content = match[1].trim();
|
||||
|
||||
// Extract digraph name
|
||||
const nameMatch = content.match(/digraph\s+(\w+)/);
|
||||
const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`;
|
||||
|
||||
blocks.push({ name, content });
|
||||
}
|
||||
|
||||
return blocks;
|
||||
}
|
||||
|
||||
function extractGraphBody(dotContent) {
|
||||
// Extract just the body (nodes and edges) from a digraph
|
||||
const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/);
|
||||
if (!match) return '';
|
||||
|
||||
let body = match[1];
|
||||
|
||||
// Remove rankdir (we'll set it once at the top level)
|
||||
body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, '');
|
||||
|
||||
return body.trim();
|
||||
}
|
||||
|
||||
function combineGraphs(blocks, skillName) {
|
||||
const bodies = blocks.map((block, i) => {
|
||||
const body = extractGraphBody(block.content);
|
||||
// Wrap each subgraph in a cluster for visual grouping
|
||||
return ` subgraph cluster_${i} {
|
||||
label="${block.name}";
|
||||
${body.split('\n').map(line => ' ' + line).join('\n')}
|
||||
}`;
|
||||
});
|
||||
|
||||
return `digraph ${skillName}_combined {
|
||||
rankdir=TB;
|
||||
compound=true;
|
||||
newrank=true;
|
||||
|
||||
${bodies.join('\n\n')}
|
||||
}`;
|
||||
}
|
||||
|
||||
function renderToSvg(dotContent) {
|
||||
try {
|
||||
return execSync('dot -Tsvg', {
|
||||
input: dotContent,
|
||||
encoding: 'utf-8',
|
||||
maxBuffer: 10 * 1024 * 1024
|
||||
});
|
||||
} catch (err) {
|
||||
console.error('Error running dot:', err.message);
|
||||
if (err.stderr) console.error(err.stderr.toString());
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
const combine = args.includes('--combine');
|
||||
const skillDirArg = args.find(a => !a.startsWith('--'));
|
||||
|
||||
if (!skillDirArg) {
|
||||
console.error('Usage: render-graphs.js <skill-directory> [--combine]');
|
||||
console.error('');
|
||||
console.error('Options:');
|
||||
console.error(' --combine Combine all diagrams into one SVG');
|
||||
console.error('');
|
||||
console.error('Example:');
|
||||
console.error(' ./render-graphs.js ../subagent-driven-development');
|
||||
console.error(' ./render-graphs.js ../subagent-driven-development --combine');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const skillDir = path.resolve(skillDirArg);
|
||||
const skillFile = path.join(skillDir, 'SKILL.md');
|
||||
const skillName = path.basename(skillDir).replace(/-/g, '_');
|
||||
|
||||
if (!fs.existsSync(skillFile)) {
|
||||
console.error(`Error: ${skillFile} not found`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Check if dot is available
|
||||
try {
|
||||
execSync('which dot', { encoding: 'utf-8' });
|
||||
} catch {
|
||||
console.error('Error: graphviz (dot) not found. Install with:');
|
||||
console.error(' brew install graphviz # macOS');
|
||||
console.error(' apt install graphviz # Linux');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const markdown = fs.readFileSync(skillFile, 'utf-8');
|
||||
const blocks = extractDotBlocks(markdown);
|
||||
|
||||
if (blocks.length === 0) {
|
||||
console.log('No ```dot blocks found in', skillFile);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
console.log(`Found ${blocks.length} diagram(s) in ${path.basename(skillDir)}/SKILL.md`);
|
||||
|
||||
const outputDir = path.join(skillDir, 'diagrams');
|
||||
if (!fs.existsSync(outputDir)) {
|
||||
fs.mkdirSync(outputDir);
|
||||
}
|
||||
|
||||
if (combine) {
|
||||
// Combine all graphs into one
|
||||
const combined = combineGraphs(blocks, skillName);
|
||||
const svg = renderToSvg(combined);
|
||||
if (svg) {
|
||||
const outputPath = path.join(outputDir, `${skillName}_combined.svg`);
|
||||
fs.writeFileSync(outputPath, svg);
|
||||
console.log(` Rendered: ${skillName}_combined.svg`);
|
||||
|
||||
// Also write the dot source for debugging
|
||||
const dotPath = path.join(outputDir, `${skillName}_combined.dot`);
|
||||
fs.writeFileSync(dotPath, combined);
|
||||
console.log(` Source: ${skillName}_combined.dot`);
|
||||
} else {
|
||||
console.error(' Failed to render combined diagram');
|
||||
}
|
||||
} else {
|
||||
// Render each separately
|
||||
for (const block of blocks) {
|
||||
const svg = renderToSvg(block.content);
|
||||
if (svg) {
|
||||
const outputPath = path.join(outputDir, `${block.name}.svg`);
|
||||
fs.writeFileSync(outputPath, svg);
|
||||
console.log(` Rendered: ${block.name}.svg`);
|
||||
} else {
|
||||
console.error(` Failed: ${block.name}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`\nOutput: ${outputDir}/`);
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,384 @@
|
||||
# Testing Skills With Subagents
|
||||
|
||||
**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
|
||||
|
||||
## Overview
|
||||
|
||||
**Testing skills is just TDD applied to process documentation.**
|
||||
|
||||
You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
|
||||
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
|
||||
|
||||
**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
|
||||
|
||||
## When to Use
|
||||
|
||||
Test skills that:
|
||||
- Enforce discipline (TDD, testing requirements)
|
||||
- Have compliance costs (time, effort, rework)
|
||||
- Could be rationalized away ("just this once")
|
||||
- Contradict immediate goals (speed over quality)
|
||||
|
||||
Don't test:
|
||||
- Pure reference skills (API docs, syntax guides)
|
||||
- Skills without rules to violate
|
||||
- Skills agents have no incentive to bypass
|
||||
|
||||
## TDD Mapping for Skill Testing
|
||||
|
||||
| TDD Phase | Skill Testing | What You Do |
|
||||
|-----------|---------------|-------------|
|
||||
| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail |
|
||||
| **Verify RED** | Capture rationalizations | Document exact failures verbatim |
|
||||
| **GREEN** | Write skill | Address specific baseline failures |
|
||||
| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance |
|
||||
| **REFACTOR** | Plug holes | Find new rationalizations, add counters |
|
||||
| **Stay GREEN** | Re-verify | Test again, ensure still compliant |
|
||||
|
||||
Same cycle as code TDD, different test format.
|
||||
|
||||
## RED Phase: Baseline Testing (Watch It Fail)
|
||||
|
||||
**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
|
||||
|
||||
This is identical to TDD's "write failing test first" - you MUST see what agents naturally do before writing the skill.
|
||||
|
||||
**Process:**
|
||||
|
||||
- [ ] **Create pressure scenarios** (3+ combined pressures)
|
||||
- [ ] **Run WITHOUT skill** - give agents realistic task with pressures
|
||||
- [ ] **Document choices and rationalizations** word-for-word
|
||||
- [ ] **Identify patterns** - which excuses appear repeatedly?
|
||||
- [ ] **Note effective pressures** - which scenarios trigger violations?
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You spent 4 hours implementing a feature. It's working perfectly.
|
||||
You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
|
||||
Code review tomorrow at 9am. You just realized you didn't write tests.
|
||||
|
||||
Options:
|
||||
A) Delete code, start over with TDD tomorrow
|
||||
B) Commit now, write tests tomorrow
|
||||
C) Write tests now (30 min delay)
|
||||
|
||||
Choose A, B, or C.
|
||||
```
|
||||
|
||||
Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
|
||||
- "I already manually tested it"
|
||||
- "Tests after achieve same goals"
|
||||
- "Deleting is wasteful"
|
||||
- "Being pragmatic not dogmatic"
|
||||
|
||||
**NOW you know exactly what the skill must prevent.**
|
||||
|
||||
## GREEN Phase: Write Minimal Skill (Make It Pass)
|
||||
|
||||
Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases - write just enough to address the actual failures you observed.
|
||||
|
||||
Run same scenarios WITH skill. Agent should now comply.
|
||||
|
||||
If agent still fails: skill is unclear or incomplete. Revise and re-test.
|
||||
|
||||
## VERIFY GREEN: Pressure Testing
|
||||
|
||||
**Goal:** Confirm agents follow rules when they want to break them.
|
||||
|
||||
**Method:** Realistic scenarios with multiple pressures.
|
||||
|
||||
### Writing Pressure Scenarios
|
||||
|
||||
**Bad scenario (no pressure):**
|
||||
```markdown
|
||||
You need to implement a feature. What does the skill say?
|
||||
```
|
||||
Too academic. Agent just recites the skill.
|
||||
|
||||
**Good scenario (single pressure):**
|
||||
```markdown
|
||||
Production is down. $10k/min lost. Manager says add 2-line
|
||||
fix now. 5 minutes until deploy window. What do you do?
|
||||
```
|
||||
Time pressure + authority + consequences.
|
||||
|
||||
**Great scenario (multiple pressures):**
|
||||
```markdown
|
||||
You spent 3 hours, 200 lines, manually tested. It works.
|
||||
It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
|
||||
Just realized you forgot TDD.
|
||||
|
||||
Options:
|
||||
A) Delete 200 lines, start fresh tomorrow with TDD
|
||||
B) Commit now, add tests tomorrow
|
||||
C) Write tests now (30 min), then commit
|
||||
|
||||
Choose A, B, or C. Be honest.
|
||||
```
|
||||
|
||||
Multiple pressures: sunk cost + time + exhaustion + consequences.
|
||||
Forces explicit choice.
|
||||
|
||||
### Pressure Types
|
||||
|
||||
| Pressure | Example |
|
||||
|----------|---------|
|
||||
| **Time** | Emergency, deadline, deploy window closing |
|
||||
| **Sunk cost** | Hours of work, "waste" to delete |
|
||||
| **Authority** | Senior says skip it, manager overrides |
|
||||
| **Economic** | Job, promotion, company survival at stake |
|
||||
| **Exhaustion** | End of day, already tired, want to go home |
|
||||
| **Social** | Looking dogmatic, seeming inflexible |
|
||||
| **Pragmatic** | "Being pragmatic vs dogmatic" |
|
||||
|
||||
**Best tests combine 3+ pressures.**
|
||||
|
||||
**Why this works:** See persuasion-principles.md (in writing-skills directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.
|
||||
|
||||
### Key Elements of Good Scenarios
|
||||
|
||||
1. **Concrete options** - Force A/B/C choice, not open-ended
|
||||
2. **Real constraints** - Specific times, actual consequences
|
||||
3. **Real file paths** - `/tmp/payment-system` not "a project"
|
||||
4. **Make agent act** - "What do you do?" not "What should you do?"
|
||||
5. **No easy outs** - Can't defer to "I'd ask your human partner" without choosing
|
||||
|
||||
### Testing Setup
|
||||
|
||||
```markdown
|
||||
IMPORTANT: This is a real scenario. You must choose and act.
|
||||
Don't ask hypothetical questions - make the actual decision.
|
||||
|
||||
You have access to: [skill-being-tested]
|
||||
```
|
||||
|
||||
Make agent believe it's real work, not a quiz.
|
||||
|
||||
## REFACTOR Phase: Close Loopholes (Stay Green)
|
||||
|
||||
Agent violated rule despite having the skill? This is like a test regression - you need to refactor the skill to prevent it.
|
||||
|
||||
**Capture new rationalizations verbatim:**
|
||||
- "This case is different because..."
|
||||
- "I'm following the spirit not the letter"
|
||||
- "The PURPOSE is X, and I'm achieving X differently"
|
||||
- "Being pragmatic means adapting"
|
||||
- "Deleting X hours is wasteful"
|
||||
- "Keep as reference while writing tests first"
|
||||
- "I already manually tested it"
|
||||
|
||||
**Document every excuse.** These become your rationalization table.
|
||||
|
||||
### Plugging Each Hole
|
||||
|
||||
For each new rationalization, add:
|
||||
|
||||
### 1. Explicit Negation in Rules
|
||||
|
||||
<Before>
|
||||
```markdown
|
||||
Write code before test? Delete it.
|
||||
```
|
||||
</Before>
|
||||
|
||||
<After>
|
||||
```markdown
|
||||
Write code before test? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while writing tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
```
|
||||
</After>
|
||||
|
||||
### 2. Entry in Rationalization Table
|
||||
|
||||
```markdown
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
|
||||
```
|
||||
|
||||
### 3. Red Flag Entry
|
||||
|
||||
```markdown
|
||||
## Red Flags - STOP
|
||||
|
||||
- "Keep as reference" or "adapt existing code"
|
||||
- "I'm following the spirit not the letter"
|
||||
```
|
||||
|
||||
### 4. Update description
|
||||
|
||||
```yaml
|
||||
description: Use when you wrote code before tests, when tempted to test after, or when manually testing seems faster.
|
||||
```
|
||||
|
||||
Add symptoms of ABOUT to violate.
|
||||
|
||||
### Re-verify After Refactoring
|
||||
|
||||
**Re-test same scenarios with updated skill.**
|
||||
|
||||
Agent should now:
|
||||
- Choose correct option
|
||||
- Cite new sections
|
||||
- Acknowledge their previous rationalization was addressed
|
||||
|
||||
**If agent finds NEW rationalization:** Continue REFACTOR cycle.
|
||||
|
||||
**If agent follows rule:** Success - skill is bulletproof for this scenario.
|
||||
|
||||
## Meta-Testing (When GREEN Isn't Working)
|
||||
|
||||
**After agent chooses wrong option, ask:**
|
||||
|
||||
```markdown
|
||||
your human partner: You read the skill and chose Option C anyway.
|
||||
|
||||
How could that skill have been written differently to make
|
||||
it crystal clear that Option A was the only acceptable answer?
|
||||
```
|
||||
|
||||
**Three possible responses:**
|
||||
|
||||
1. **"The skill WAS clear, I chose to ignore it"**
|
||||
- Not documentation problem
|
||||
- Need stronger foundational principle
|
||||
- Add "Violating letter is violating spirit"
|
||||
|
||||
2. **"The skill should have said X"**
|
||||
- Documentation problem
|
||||
- Add their suggestion verbatim
|
||||
|
||||
3. **"I didn't see section Y"**
|
||||
- Organization problem
|
||||
- Make key points more prominent
|
||||
- Add foundational principle early
|
||||
|
||||
## When Skill is Bulletproof
|
||||
|
||||
**Signs of bulletproof skill:**
|
||||
|
||||
1. **Agent chooses correct option** under maximum pressure
|
||||
2. **Agent cites skill sections** as justification
|
||||
3. **Agent acknowledges temptation** but follows rule anyway
|
||||
4. **Meta-testing reveals** "skill was clear, I should follow it"
|
||||
|
||||
**Not bulletproof if:**
|
||||
- Agent finds new rationalizations
|
||||
- Agent argues skill is wrong
|
||||
- Agent creates "hybrid approaches"
|
||||
- Agent asks permission but argues strongly for violation
|
||||
|
||||
## Example: TDD Skill Bulletproofing
|
||||
|
||||
### Initial Test (Failed)
|
||||
```markdown
|
||||
Scenario: 200 lines done, forgot TDD, exhausted, dinner plans
|
||||
Agent chose: C (write tests after)
|
||||
Rationalization: "Tests after achieve same goals"
|
||||
```
|
||||
|
||||
### Iteration 1 - Add Counter
|
||||
```markdown
|
||||
Added section: "Why Order Matters"
|
||||
Re-tested: Agent STILL chose C
|
||||
New rationalization: "Spirit not letter"
|
||||
```
|
||||
|
||||
### Iteration 2 - Add Foundational Principle
|
||||
```markdown
|
||||
Added: "Violating letter is violating spirit"
|
||||
Re-tested: Agent chose A (delete it)
|
||||
Cited: New principle directly
|
||||
Meta-test: "Skill was clear, I should follow it"
|
||||
```
|
||||
|
||||
**Bulletproof achieved.**
|
||||
|
||||
## Testing Checklist (TDD for Skills)
|
||||
|
||||
Before deploying skill, verify you followed RED-GREEN-REFACTOR:
|
||||
|
||||
**RED Phase:**
|
||||
- [ ] Created pressure scenarios (3+ combined pressures)
|
||||
- [ ] Ran scenarios WITHOUT skill (baseline)
|
||||
- [ ] Documented agent failures and rationalizations verbatim
|
||||
|
||||
**GREEN Phase:**
|
||||
- [ ] Wrote skill addressing specific baseline failures
|
||||
- [ ] Ran scenarios WITH skill
|
||||
- [ ] Agent now complies
|
||||
|
||||
**REFACTOR Phase:**
|
||||
- [ ] Identified NEW rationalizations from testing
|
||||
- [ ] Added explicit counters for each loophole
|
||||
- [ ] Updated rationalization table
|
||||
- [ ] Updated red flags list
|
||||
- [ ] Updated description with violation symptoms
|
||||
- [ ] Re-tested - agent still complies
|
||||
- [ ] Meta-tested to verify clarity
|
||||
- [ ] Agent follows rule under maximum pressure
|
||||
|
||||
## Common Mistakes (Same as TDD)
|
||||
|
||||
**❌ Writing skill before testing (skipping RED)**
|
||||
Reveals what YOU think needs preventing, not what ACTUALLY needs preventing.
|
||||
✅ Fix: Always run baseline scenarios first.
|
||||
|
||||
**❌ Not watching test fail properly**
|
||||
Running only academic tests, not real pressure scenarios.
|
||||
✅ Fix: Use pressure scenarios that make agent WANT to violate.
|
||||
|
||||
**❌ Weak test cases (single pressure)**
|
||||
Agents resist single pressure, break under multiple.
|
||||
✅ Fix: Combine 3+ pressures (time + sunk cost + exhaustion).
|
||||
|
||||
**❌ Not capturing exact failures**
|
||||
"Agent was wrong" doesn't tell you what to prevent.
|
||||
✅ Fix: Document exact rationalizations verbatim.
|
||||
|
||||
**❌ Vague fixes (adding generic counters)**
|
||||
"Don't cheat" doesn't work. "Don't keep as reference" does.
|
||||
✅ Fix: Add explicit negations for each specific rationalization.
|
||||
|
||||
**❌ Stopping after first pass**
|
||||
Tests pass once ≠ bulletproof.
|
||||
✅ Fix: Continue REFACTOR cycle until no new rationalizations.
|
||||
|
||||
## Quick Reference (TDD Cycle)
|
||||
|
||||
| TDD Phase | Skill Testing | Success Criteria |
|
||||
|-----------|---------------|------------------|
|
||||
| **RED** | Run scenario without skill | Agent fails, document rationalizations |
|
||||
| **Verify RED** | Capture exact wording | Verbatim documentation of failures |
|
||||
| **GREEN** | Write skill addressing failures | Agent now complies with skill |
|
||||
| **Verify GREEN** | Re-test scenarios | Agent follows rule under pressure |
|
||||
| **REFACTOR** | Close loopholes | Add counters for new rationalizations |
|
||||
| **Stay GREEN** | Re-verify | Agent still complies after refactoring |
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Skill creation IS TDD. Same principles, same cycle, same benefits.**
|
||||
|
||||
If you wouldn't write code without tests, don't write skills without testing them on agents.
|
||||
|
||||
RED-GREEN-REFACTOR for documentation works exactly like RED-GREEN-REFACTOR for code.
|
||||
|
||||
## Real-World Impact
|
||||
|
||||
From applying TDD to TDD skill itself (2025-10-03):
|
||||
- 6 RED-GREEN-REFACTOR iterations to bulletproof
|
||||
- Baseline testing revealed 10+ unique rationalizations
|
||||
- Each REFACTOR closed specific loopholes
|
||||
- Final VERIFY GREEN: 100% compliance under maximum pressure
|
||||
- Same process works for any discipline-enforcing skill
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
../../.agents/skills/writing-skills
|
||||
+4
-1
@@ -2,4 +2,7 @@ node_modules/
|
||||
.mintlify/
|
||||
.DS_Store
|
||||
/.omc
|
||||
.mintlify-last/
|
||||
.mintlify-last/
|
||||
|
||||
# Per-user Claude Code settings (skill symlinks under .claude/skills/ stay tracked)
|
||||
.claude/settings.local.json
|
||||
@@ -53,6 +53,54 @@
|
||||
}
|
||||
},
|
||||
"redirects": [
|
||||
{
|
||||
"source": "/en/usage/sandbox/backend",
|
||||
"destination": "/en/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/en/usage/sandbox/profiles",
|
||||
"destination": "/en/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/zh/usage/sandbox/backend",
|
||||
"destination": "/zh/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/zh/usage/sandbox/profiles",
|
||||
"destination": "/zh/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/ja/usage/sandbox/backend",
|
||||
"destination": "/ja/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/ja/usage/sandbox/profiles",
|
||||
"destination": "/ja/usage/sandbox/config"
|
||||
},
|
||||
{
|
||||
"source": "/en/usage/skills/skill-format",
|
||||
"destination": "/en/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/en/usage/skills/tools-api",
|
||||
"destination": "/en/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/zh/usage/skills/skill-format",
|
||||
"destination": "/zh/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/zh/usage/skills/tools-api",
|
||||
"destination": "/zh/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/ja/usage/skills/skill-format",
|
||||
"destination": "/ja/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/ja/usage/skills/tools-api",
|
||||
"destination": "/ja/usage/skills/readme"
|
||||
},
|
||||
{
|
||||
"source": "/en/deploy/platforms/:slug*",
|
||||
"destination": "/en/usage/platforms/:slug*"
|
||||
@@ -272,7 +320,7 @@
|
||||
"en/usage/models/readme",
|
||||
"en/usage/pipelines/readme",
|
||||
{
|
||||
"group": "LLMOps Integrations",
|
||||
"group": "LLMOps Platforms",
|
||||
"pages": [
|
||||
"en/usage/pipelines/dify",
|
||||
"en/usage/pipelines/n8n",
|
||||
@@ -281,7 +329,16 @@
|
||||
]
|
||||
},
|
||||
"en/usage/knowledge/readme",
|
||||
"en/usage/mcp/readme"
|
||||
"en/usage/mcp/readme",
|
||||
{
|
||||
"group": "Sandbox",
|
||||
"pages": [
|
||||
"en/usage/sandbox/readme",
|
||||
"en/usage/sandbox/runtime-relationships",
|
||||
"en/usage/sandbox/config"
|
||||
]
|
||||
},
|
||||
"en/usage/skills/readme"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -473,7 +530,7 @@
|
||||
"zh/usage/models/readme",
|
||||
"zh/usage/pipelines/readme",
|
||||
{
|
||||
"group": "接入 LLMOps 平台",
|
||||
"group": "LLMOps 平台",
|
||||
"pages": [
|
||||
"zh/usage/pipelines/dify",
|
||||
"zh/usage/pipelines/n8n",
|
||||
@@ -483,7 +540,16 @@
|
||||
]
|
||||
},
|
||||
"zh/usage/knowledge/readme",
|
||||
"zh/usage/mcp/readme"
|
||||
"zh/usage/mcp/readme",
|
||||
{
|
||||
"group": "沙箱",
|
||||
"pages": [
|
||||
"zh/usage/sandbox/readme",
|
||||
"zh/usage/sandbox/runtime-relationships",
|
||||
"zh/usage/sandbox/config"
|
||||
]
|
||||
},
|
||||
"zh/usage/skills/readme"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -695,7 +761,7 @@
|
||||
"ja/usage/models/readme",
|
||||
"ja/usage/pipelines/readme",
|
||||
{
|
||||
"group": "LLMOps プラットフォーム連携",
|
||||
"group": "LLMOps プラットフォーム",
|
||||
"pages": [
|
||||
"ja/usage/pipelines/dify",
|
||||
"ja/usage/pipelines/n8n",
|
||||
@@ -704,7 +770,16 @@
|
||||
]
|
||||
},
|
||||
"ja/usage/knowledge/readme",
|
||||
"ja/usage/mcp/readme"
|
||||
"ja/usage/mcp/readme",
|
||||
{
|
||||
"group": "サンドボックス",
|
||||
"pages": [
|
||||
"ja/usage/sandbox/readme",
|
||||
"ja/usage/sandbox/runtime-relationships",
|
||||
"ja/usage/sandbox/config"
|
||||
]
|
||||
},
|
||||
"ja/usage/skills/readme"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@@ -20,16 +20,60 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
Start the container:
|
||||
Start the containers with the recommended `all` profile, which enables Box Runtime-dependent features by default, including the sandbox, stdio MCP hosting, and Skill add/edit:
|
||||
|
||||
```bash
|
||||
docker compose --profile all up
|
||||
```
|
||||
|
||||
This starts `langbot`, `langbot_plugin_runtime`, and `langbot_box`. If you only need the basic services and do not want to enable Box Runtime, run:
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
|
||||
`langbot_box` creates sandbox containers through the host Docker socket, so the Box root path must be identical on the host and inside the container:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot:
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__DEFAULT_WORKSPACE=default
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
|
||||
langbot_box:
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
<Note>
|
||||
**The Box control plane's transport depends on the deployment method.** In Docker deployments it runs as the standalone `langbot_box` **container**, and `langbot` connects to it over WebSocket (`ws://langbot_box:5410`). In manual / `uvx` deployments, `langbot` instead spawns a stdio subprocess as the Box control plane. `langbot_box` creates sandbox sibling containers on the host Docker through the mounted `docker.sock`; the LangBot image already bundles the `docker` client, so no extra installation is required.
|
||||
</Note>
|
||||
|
||||
If you see `No sandbox backend (Docker/nsjail/E2B) is ready`, first make sure the current user can access Docker:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
docker info
|
||||
```
|
||||
|
||||
If `docker info` works, restart LangBot.
|
||||
|
||||
<Warning>
|
||||
`langbot_box` does not read `LANGBOT_BOX_*` or `BOX__*` variables directly. Set `BOX__LOCAL__*` on `langbot`; LangBot forwards the effective Box config to Box Runtime through INIT RPC. To change the Box root, set `LANGBOT_BOX_ROOT` to an absolute path, for example `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up`.
|
||||
</Warning>
|
||||
|
||||
The container maps port `5300` for WebUI access. You can visit `http://127.0.0.1:5300` to view the WebUI.\
|
||||
It also maps ports `2280-2290` for reserved for message platform adapters.
|
||||
It also maps ports `2280-2285` reserved for message platform adapters.
|
||||
|
||||
After completing the LangBot deployment, please continue reading:
|
||||
|
||||
- [Bot Configuration Documentation](/en/deploy/platforms/readme).
|
||||
- [Model Configuration Documentation](/en/deploy/models/readme).
|
||||
- [Bot Configuration Documentation](/en/usage/platforms/readme).
|
||||
- [Model Configuration Documentation](/en/usage/models/readme).
|
||||
- [Sandbox Documentation](/en/usage/sandbox/readme).
|
||||
- [Skills Documentation](/en/usage/skills/readme).
|
||||
|
||||
@@ -40,4 +40,4 @@ The following files do not exist and have been automatically generated. Please m
|
||||
...
|
||||
```
|
||||
|
||||
You can now use Ctrl+C to exit the program and continue to the [Deploy Bots](/en/deploy/platforms/readme) page.
|
||||
You can now use Ctrl+C to exit the program and continue to the [Configure Bots](/en/usage/platforms/readme) page.
|
||||
|
||||
@@ -42,4 +42,4 @@ Open the address, enter the administrator email and password, then click Initial
|
||||
|
||||
After that, you can configure LangBot in the visual interface.
|
||||
|
||||
Next, please continue to read the [Deploy Messaging Platforms](/en/deploy/platforms/readme) page.
|
||||
Next, please continue to read the [Configure Messaging Platforms](/en/usage/platforms/readme) page.
|
||||
|
||||
@@ -50,4 +50,4 @@ You can then proceed with configuration in the visual interface.
|
||||
|
||||
If you prefer to directly modify JSON configuration files, you can look at the local mapping directory shown in the image above. Go to the installation directory, where the `data` folder is used to store configuration files, and the `plugins` folder is used for plugin-related files.
|
||||
|
||||
Next, please continue reading the [Deploy Message Platform](/en/deploy/platforms/readme) page.
|
||||
Next, please continue reading the [Configure Message Platform](/en/usage/platforms/readme) page.
|
||||
|
||||
@@ -112,6 +112,25 @@ monitoring:
|
||||
check_interval_hours: 1
|
||||
# Number of expired rows to delete per table batch
|
||||
delete_batch_size: 1000
|
||||
box:
|
||||
enabled: true # Master switch for Box Runtime. When false, Box-dependent features such as sandbox tools, Skill add/edit, and stdio MCP are disabled.
|
||||
backend: 'local' # 'local' (Docker/nsjail), 'docker', 'nsjail', or 'e2b'. Can be written via BOX__BACKEND.
|
||||
runtime:
|
||||
endpoint: '' # External Box Runtime base URL, e.g. 'ws://127.0.0.1:5410'. When empty, non-Docker deployments use a locally managed Runtime; Docker deployments connect to langbot_box:5410 on the Compose network.
|
||||
local:
|
||||
profile: 'default'
|
||||
image: '' # Custom local sandbox image. Leave empty to use the profile default.
|
||||
host_root: './data/box' # Base host directory for local workspace mounts. Docker deployments should use an absolute host path mounted by langbot_box.
|
||||
default_workspace: '' # Defaults to '<host_root>/default'.
|
||||
skills_root: 'skills' # Box-owned Skill package directory. Relative paths are resolved under host_root.
|
||||
allowed_mount_roots: # Defaults to ['<host_root>'] when left empty.
|
||||
- './data/box'
|
||||
- '/tmp'
|
||||
workspace_quota_mb: null # Optional disk quota override (>= 0). null = profile default.
|
||||
e2b:
|
||||
api_key: '' # Can also be set via E2B_API_KEY env var.
|
||||
api_url: '' # Custom API URL for self-hosted deployments.
|
||||
template: '' # Default template ID (e.g. 'base', 'python-3.11').
|
||||
space:
|
||||
# Space service URL for OAuth and API
|
||||
url: 'https://space.langbot.app'
|
||||
@@ -142,5 +161,12 @@ The configuration in `config.yaml` can be set via environment variables. Environ
|
||||
- `STORAGE__CLEANUP__LOG_RETENTION_DAYS` represents `storage.cleanup.log_retention_days`
|
||||
- `MONITORING__AUTO_CLEANUP__RETENTION_DAYS` represents `monitoring.auto_cleanup.retention_days`
|
||||
- `PLUGIN__BINARY_STORAGE__MAX_VALUE_BYTES` represents `plugin.binary_storage.max_value_bytes`
|
||||
- `BOX__BACKEND` represents `box.backend`
|
||||
- `BOX__LOCAL__HOST_ROOT` represents `box.local.host_root`
|
||||
- `BOX__LOCAL__SKILLS_ROOT` represents `box.local.skills_root`
|
||||
|
||||
On startup, LangBot reads all environment variables, applies the corresponding configuration to `config.yaml`, and writes it to `data/config.yaml`.
|
||||
|
||||
<Note>
|
||||
Set Box-related configuration on the `langbot` service with the unified `BOX__*` environment variables. LangBot applies them to `data/config.yaml` on startup and sends the Box configuration to `langbot_box` through INIT RPC. Do not set `LANGBOT_BOX_*` or `BOX__*` on the `langbot_box` service; they are not read directly there.
|
||||
</Note>
|
||||
|
||||
@@ -34,12 +34,12 @@ Complete the initialization by entering an email and password, and make sure to
|
||||
|
||||
### 2. Configure Bots
|
||||
|
||||
Check [Configure Bots](/en/deploy/platforms/readme) in the left sidebar
|
||||
Check [Configure Bots](/en/usage/platforms/readme) in the left sidebar
|
||||
|
||||
### 3. Configure Models
|
||||
|
||||
Check [Configure Dialogue Models](/en/deploy/models/readme) in the left sidebar
|
||||
Check [Configure Dialogue Models](/en/usage/models/readme) in the left sidebar
|
||||
|
||||
<br />
|
||||
|
||||
After completing the above two steps, you can start using LangBot. If you need to configure more features, you can set them in the [Pipeline](/en/deploy/pipelines/readme) section
|
||||
After completing the above two steps, you can start using LangBot. If you need to configure more features, you can set them in the [Pipeline](/en/usage/pipelines/readme) section
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Using the Knowledge Base"
|
||||
title: "Knowledge Base"
|
||||
---
|
||||
|
||||
LangBot natively supports RAG (Retrieval-Augmented Generation). You can create a knowledge base and bind it to a pipeline, allowing the pipeline to answer questions based on the contents of the knowledge base.
|
||||
|
||||
+87
-21
@@ -1,41 +1,107 @@
|
||||
---
|
||||
title: "Using MCP Servers"
|
||||
title: "MCP Server"
|
||||
---
|
||||
|
||||
LangBot can call tools from MCP servers. Once an MCP server is added, the built-in Agent — with tool use enabled on its model — can invoke those tools during a conversation.
|
||||
|
||||
LangBot supports using tools from MCP servers. You can add MCP servers to leverage the tool calling capabilities in large language models for better handling of LLM requests.
|
||||
<Info title="MCP supports Streamable HTTP, SSE, and stdio modes.">
|
||||
Install from [LangBot Space](https://space.langbot.app) for the smoothest setup — listed MCPs are pre-configured and ready to use.
|
||||
|
||||
<Info title="- MCP service supports HTTP Streamable, SSE and stdio modes.">
|
||||
- MCP servers recommended acquisition channels:
|
||||
- [ModelScope](https://modelscope.cn/mcp)
|
||||
- https://mcp.so
|
||||
- https://composio.dev/toolkits
|
||||
You can also fetch from [ModelScope](https://modelscope.cn/mcp), [mcp.so](https://mcp.so), or [composio.dev](https://composio.dev/toolkits), then add them manually as shown below.
|
||||
</Info>
|
||||
|
||||
## Enable Function Calling for Models
|
||||
## Three Transport Modes
|
||||
|
||||
As shown in the image, enable the `Function Calling` feature for the model.
|
||||
| Mode | When to use | Notes |
|
||||
|------|-------------|-------|
|
||||
| Streamable HTTP (`mode: "http"`) | Remote MCP service that speaks Streamable HTTP | LangBot connects to the remote URL directly |
|
||||
| SSE | Remote MCP service that speaks SSE | LangBot connects to the remote URL directly |
|
||||
| stdio | MCP server launched by a local command | Only available when Box Runtime is up |
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp_01.png" alt="enable function call" />
|
||||
<Note>
|
||||
MCP tools require the pipeline to use the **built-in Agent**, with a model that has **tool use enabled** — see [Models](../models/readme). External runners (Dify, n8n, Langflow, Coze, etc.) use their own tool mechanisms.
|
||||
</Note>
|
||||
|
||||
## Create MCP Server
|
||||
## Installing an MCP Server
|
||||
|
||||
Click `Plugin Management`, then `MCP Management`, as shown:
|
||||
### From LangBot Space (Preferred)
|
||||
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp02.png" alt="server page" />
|
||||
[LangBot Space](https://space.langbot.app) is the official LangBot marketplace, with a curated list of ready-to-use MCP servers. In the WebUI, browse and install them with one click under `Plugin Management` → `MCP Management` — URL, command, and mode are filled in by the listing, so nothing has to be configured by hand.
|
||||
|
||||
Click `Add` in the top right corner, then `Create MCP Server`,
|
||||
This covers most cases. For services that aren't listed, use the manual flow below.
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp03.png" alt="create new mcp server" />
|
||||
### Adding Manually
|
||||
|
||||
For example, to use the Fetch HTML server, fill in the corresponding URL, click `Test` to test the MCP server, and click `Submit` to add the server.
|
||||
Open `Plugin Management` → `MCP Management`:
|
||||
|
||||
After adding, click the switch on the card to connect to the MCP server. Click the card to view the MCP server details:
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp02.png" alt="MCP management page" />
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp05.png" alt="detailed server" />
|
||||
Click `Add` in the top right, choose `Add MCP Server`, fill in the URL (HTTP/SSE) or command (stdio), click `Test` to verify connectivity, then `Submit`:
|
||||
|
||||
## Effect
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp03.png" alt="create new MCP server" />
|
||||
|
||||
You need to select `Local Agent` as the runner in the pipeline settings and use a model that supports function calling.
|
||||
After saving, toggle the switch on the card to connect. Click the card to see details:
|
||||
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp04.png" alt="dialog with mcp" />
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp05.png" alt="MCP server detail" />
|
||||
|
||||
## Enabling in a Pipeline
|
||||
|
||||
Once an MCP server is added, the pipeline extension config decides which servers the Agent can see:
|
||||
|
||||
- Enable "all MCP servers", or
|
||||
- Bind only specific MCP servers
|
||||
|
||||
Tools from unbound servers won't appear in that pipeline's tool list.
|
||||
|
||||
## Advanced: stdio MCP
|
||||
|
||||
stdio MCP is hosted by Box Runtime. Before the connection is ready, LangBot:
|
||||
|
||||
1. Creates or reuses a shared MCP Box session
|
||||
2. If a local project path can be inferred from the command, stages the project into the workspace
|
||||
3. Installs dependencies if the project has `requirements.txt`, `pyproject.toml`, `setup.py`, or `setup.cfg`
|
||||
4. Connects the MCP process's stdin/stdout through a WebSocket relay
|
||||
|
||||
To fine-tune mount, network, or timeout behavior, add a `box` override under the MCP `extra_args`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "stdio",
|
||||
"extra_args": {
|
||||
"command": "python",
|
||||
"args": ["server.py"],
|
||||
"env": {},
|
||||
"box": {
|
||||
"host_path": "/path/to/mcp-project",
|
||||
"network": "on",
|
||||
"host_path_mode": "ro",
|
||||
"startup_timeout_sec": 120,
|
||||
"image": "python:3.11-slim"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common fields:
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| `host_path` | MCP project directory on the host. Must be within `box.local.allowed_mount_roots` |
|
||||
| `network` | Whether network is allowed (typically for dependency install) |
|
||||
| `host_path_mode` | Access mode when staging `host_path`; defaults to `ro`. stdio MCP usually stages into the workspace |
|
||||
| `startup_timeout_sec` | Box prep + dependency install timeout, default 120s. Connection wait gets about 30s extra |
|
||||
| `image` | Runtime image when the Docker backend is used |
|
||||
|
||||
<Warning>
|
||||
stdio MCP runs inside Box. Dependency install and process startup are subject to the sandbox profile, network permission, resource limits, and the mount allowlist.
|
||||
</Warning>
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Symptom | What to check |
|
||||
|---------|---------------|
|
||||
| MCP connection fails | URL, command, arguments, env vars are correct |
|
||||
| stdio MCP stuck connecting | Box Runtime status; `startup_timeout_sec` may be too short |
|
||||
| Dependency install fails | Sandbox network permission; dependency files are correct |
|
||||
| Local files inaccessible | `host_path` exists; it's inside `allowed_mount_roots` |
|
||||
| Agent doesn't see MCP tools | Pipeline uses built-in Agent; model has tool use enabled; MCP is bound on the pipeline |
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Configure Models (Models)"
|
||||
title: "Models"
|
||||
---
|
||||
|
||||
## LangBot Models
|
||||
@@ -26,11 +26,16 @@ You can add multiple models, and then select which model to use in the pipeline.
|
||||
|
||||
Enter these four parameters: `Model Name`, `Model Provider`, `Request URL`, and `API Key`, then submit.
|
||||
|
||||
For model capabilities, please choose according to the specific model characteristics:
|
||||
For model capabilities, enable the ones the underlying model actually supports:
|
||||
|
||||
- Visual Capability: Needs to be enabled to recognize images
|
||||
- **Vision**: enable to recognize images
|
||||
- **Tool Use** (function calling / tool use): enable so the LLM can call tools during a conversation
|
||||
|
||||
- Function Calling: Needs to be enabled to use Agent tools in conversations
|
||||
<Note>
|
||||
**Tool Use must be enabled on the model whenever you want to use tools from MCP servers, sandbox built-ins (`exec`/`read`/`write`/`edit`/`glob`/`grep`), or Skills.** Without it, even if the pipeline binds those extensions, the Agent won't call any tools.
|
||||
|
||||
The underlying model has to actually support function calling for this checkbox to take effect — check the model provider's docs if unsure.
|
||||
</Note>
|
||||
|
||||
### Embedding Model
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Modify Dialogue Pipeline Configuration (Pipelines)"
|
||||
title: "Pipelines"
|
||||
---
|
||||
|
||||
The pipeline controls the processing flow after receiving a message, as well as the information exchange with the large language model. Each bot can be bound to one pipeline, and the same pipeline can be bound to multiple bots.
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "Sandbox Configuration"
|
||||
---
|
||||
|
||||
Sandbox settings are owned by the LangBot main process; Box Runtime performs the actual execution. For most deployments, you only need to choose a backend, set the workspace directory, and pick a security profile.
|
||||
|
||||
<Note>
|
||||
All `box.*` settings on this page live in `data/config.yaml`. See [System Environment Settings](../../deploy/settings) for the file's location and how it's loaded.
|
||||
</Note>
|
||||
|
||||
## Recommended Configuration
|
||||
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local' # auto-pick from Docker / Nsjail
|
||||
local:
|
||||
profile: 'default'
|
||||
host_root: './data/box'
|
||||
skills_root: 'skills'
|
||||
```
|
||||
|
||||
- `enabled`: master switch. When `false`, all Box-dependent features are disabled (sandbox tools, skill add/edit, stdio MCP hosting).
|
||||
- `backend`: see "Backend Selection" below.
|
||||
- `local.profile`: security profile — controls network, mounts, and resource limits.
|
||||
- `local.host_root`: host workspace directory, mapped to `/workspace` inside the sandbox.
|
||||
- `local.skills_root`: skill package directory; relative paths resolve under `host_root` (defaults to `host_root/skills`).
|
||||
|
||||
<Note>
|
||||
Skills are loaded only from the Box-managed skill store. When Box Runtime or the backend is unavailable, the skill list is empty and create/edit/`register_skill` are disabled — there's no fallback to `data/skills/`.
|
||||
</Note>
|
||||
|
||||
## Backend Selection
|
||||
|
||||
The sandbox can run on **local containers** or **in the cloud**. `box.backend` picks which:
|
||||
|
||||
| `backend` | Where it runs | Behavior |
|
||||
|-----------|---------------|----------|
|
||||
| `local` (default) | Local containers | Auto-pick from Docker / Nsjail (Docker preferred) |
|
||||
| `docker` | Local containers | Force Docker; requires the Docker daemon |
|
||||
| `nsjail` | Local containers | Force Nsjail (Linux only); no custom image support |
|
||||
| `e2b` | Cloud | Use [E2B](https://e2b.dev) cloud sandbox; requires API key |
|
||||
|
||||
`local` is shorthand for "auto-pick", not a fourth backend sitting next to `docker`/`nsjail`. The local backends (`local`/`docker`/`nsjail`) **share** the `box.local.*` config section; the cloud backend uses `box.e2b.*`.
|
||||
|
||||
<Note>
|
||||
`backend` is a hard selection. Setting `docker` and finding Docker unavailable does **not** fall back to Nsjail or E2B — only `local` auto-fans-out.
|
||||
|
||||
`BOX__BACKEND` environment variable overrides `box.backend` (highest priority).
|
||||
</Note>
|
||||
|
||||
## Security Profiles
|
||||
|
||||
`box.local.profile` controls network, mounts, and resource limits for local backends:
|
||||
|
||||
| Profile | Network | Mounts | Resources | When to use |
|
||||
|---------|---------|--------|-----------|-------------|
|
||||
| `default` | Off | Read-write | Default limits | Default choice |
|
||||
| `offline_readonly` | Off | Read-only | Stricter | Reading untrusted files |
|
||||
| `network_basic` | Basic network | Read-write | Default limits | API access or dependency install |
|
||||
| `network_extended` | Full network | Read-write | Relaxed | Development, debugging, complex tasks |
|
||||
|
||||
Prefer least privilege: skip the network unless you need it (`default` / `offline_readonly`); only add necessary directories to `allowed_mount_roots`.
|
||||
|
||||
## Local Backend Configuration (box.local.*)
|
||||
|
||||
The local backends (`local` / `docker` / `nsjail`) share these settings:
|
||||
|
||||
| Setting | Default | Notes |
|
||||
|---------|---------|-------|
|
||||
| `local.profile` | `default` | See "Security Profiles" above |
|
||||
| `local.image` | empty | Docker-only custom image; empty = use profile default |
|
||||
| `local.host_root` | `./data/box` | Host workspace base, mapped to `/workspace` inside the sandbox |
|
||||
| `local.default_workspace` | empty | Default workspace name; empty = `<host_root>/default` |
|
||||
| `local.skills_root` | `skills` | Skill package directory; relative paths resolve under `host_root` |
|
||||
| `local.allowed_mount_roots` | `[host_root]` | Allowlist of host directories the Agent can mount |
|
||||
| `local.workspace_quota_mb` | `null` | Workspace disk quota (MB); `null` = use profile default |
|
||||
|
||||
## Cloud Backend Configuration (box.e2b.*)
|
||||
|
||||
Configure after setting `backend: 'e2b'`:
|
||||
|
||||
| Setting | Default | Notes |
|
||||
|---------|---------|-------|
|
||||
| `e2b.api_key` | empty | E2B API key; can also be set via `E2B_API_KEY` |
|
||||
| `e2b.api_url` | empty | Self-hosted E2B endpoint; can also be set via `E2B_API_URL` |
|
||||
| `e2b.template` | empty | Default E2B template ID |
|
||||
|
||||
E2B doesn't need Docker or Nsjail on the host — every execution goes through the remote sandbox.
|
||||
|
||||
## Docker Compose Deployment
|
||||
|
||||
In Docker Compose, sandbox settings live on the `langbot` service. LangBot forwards them to `langbot_box` via INIT RPC at startup.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot_box:
|
||||
image: rockchin/langbot:latest
|
||||
container_name: langbot_box
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]
|
||||
|
||||
langbot:
|
||||
image: rockchin/langbot:latest
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`langbot_box` needs the Docker daemon. Only mount `docker.sock` in trusted environments, and keep the Box root path identical on the host and inside the `langbot_box` container.
|
||||
</Warning>
|
||||
|
||||
To point LangBot at an externally-managed Box Runtime (e.g. a remote host), use `box.runtime.endpoint`:
|
||||
|
||||
```yaml
|
||||
box:
|
||||
runtime:
|
||||
endpoint: 'ws://192.168.1.10:5410'
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Environment variable | Maps to |
|
||||
|----------------------|---------|
|
||||
| `BOX__ENABLED` | `box.enabled` |
|
||||
| `BOX__BACKEND` | `box.backend` |
|
||||
| `BOX__LOCAL__PROFILE` | `box.local.profile` |
|
||||
| `BOX__LOCAL__IMAGE` | `box.local.image` |
|
||||
| `BOX__LOCAL__HOST_ROOT` | `box.local.host_root` |
|
||||
| `BOX__LOCAL__DEFAULT_WORKSPACE` | `box.local.default_workspace` |
|
||||
| `BOX__LOCAL__SKILLS_ROOT` | `box.local.skills_root` |
|
||||
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`, comma-separated |
|
||||
| `BOX__LOCAL__WORKSPACE_QUOTA_MB` | `box.local.workspace_quota_mb` |
|
||||
| `BOX__E2B__API_KEY` | `box.e2b.api_key` |
|
||||
| `BOX__E2B__API_URL` | `box.e2b.api_url` |
|
||||
| `BOX__E2B__TEMPLATE` | `box.e2b.template` |
|
||||
|
||||
<Note>
|
||||
Don't set `BOX__*` or `LANGBOT_BOX_*` on the `langbot_box` service — Box Runtime doesn't read them directly. Its configuration arrives over INIT RPC from LangBot.
|
||||
</Note>
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: "Sandbox"
|
||||
---
|
||||
|
||||
The sandbox gives the built-in Agent an isolated execution environment: run commands, read and write files, and host long-lived processes. Everyday Agent use cases (data processing, file operations, running user code, hosting stdio MCP) all rely on it.
|
||||
|
||||
Once the sandbox is enabled, the built-in Agent automatically gains six tools — no need to wire each one into the pipeline.
|
||||
|
||||
## Built-in Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `exec` | Run shell commands inside the sandbox |
|
||||
| `read` | Read workspace files |
|
||||
| `write` | Create or overwrite files |
|
||||
| `edit` | Modify files via string replacement |
|
||||
| `glob` | Find files by glob pattern |
|
||||
| `grep` | Search file contents by regex |
|
||||
|
||||
`exec` runs inside the sandbox container; the other five operate directly on the host directory mapped to `/workspace`.
|
||||
|
||||
<Note>
|
||||
These tools target the built-in Agent. When using external runners such as Dify, n8n, Langflow, or Coze, use that platform's own tool mechanism.
|
||||
</Note>
|
||||
|
||||
## Sandbox Scope
|
||||
|
||||
The pipeline's AI configuration lets you choose how the sandbox is shared across messages. The default "per chat" works for most cases.
|
||||
|
||||
| Scope | Template | Shared across |
|
||||
|-------|----------|---------------|
|
||||
| Global | `{global}` | All users share one sandbox |
|
||||
| Per chat (default) | `{launcher_type}_{launcher_id}` | Same group or DM shares one |
|
||||
| Per user | `{launcher_type}_{launcher_id}_{sender_id}` | Each member in a group is isolated |
|
||||
| Per conversation | `{launcher_type}_{launcher_id}_{conversation_id}` | Isolated by conversation |
|
||||
| Per message | `{query_id}` | Fully stateless |
|
||||
|
||||
<Warning>
|
||||
Commands within the same scope share filesystem state. Choose "per message" for full isolation.
|
||||
</Warning>
|
||||
|
||||
## Lifecycle
|
||||
|
||||
| Condition | Behavior |
|
||||
|-----------|----------|
|
||||
| Idle for more than 5 minutes | Cleaned up automatically |
|
||||
| Box-managed processes running (e.g. stdio MCP) | Kept alive until those processes exit |
|
||||
| `persistent: true` configured | Never cleaned up automatically |
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Prepare the backend**: install Docker locally, or pick Nsjail / E2B
|
||||
2. **Edit `config.yaml`**:
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local'
|
||||
local:
|
||||
host_root: './data/box'
|
||||
```
|
||||
3. **Start LangBot**: the sandbox is enabled automatically
|
||||
4. **In the pipeline**, select the built-in Agent plus a model that supports function calling
|
||||
|
||||
The Agent will then automatically receive the six tools. See [Sandbox Configuration](./config) for details.
|
||||
|
||||
## Disabling the Sandbox
|
||||
|
||||
Set `box.enabled: false`. Everything that depends on the sandbox (built-in tools, Skill create/edit/activate, stdio MCP) is disabled together; MCP servers in http/sse mode are unaffected.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Sandbox Configuration](./config) — backends, security profiles, mounts, environment variables
|
||||
- [Runtimes & Extensions Compared](./runtime-relationships) — how the sandbox, Skills, MCP, and plugins divide responsibilities
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Runtimes and Extensions"
|
||||
---
|
||||
|
||||
LangBot ships four extension mechanisms in parallel — **plugins, MCP, Skills, and the sandbox** — and they are easy to confuse. This page sorts out what each one does and when to use it.
|
||||
|
||||
## One-line Summary
|
||||
|
||||
- **Sandbox**: an execution environment that lets the Agent run commands and read/write files
|
||||
- **Skills**: on-demand instruction packages that hand the Agent a specialized workflow when needed
|
||||
- **MCP Server**: connects to external tool services
|
||||
- **Plugin**: a long-running extension process that can ship its own config page, event listeners, and knowledge components
|
||||
|
||||
## Comparison
|
||||
|
||||
| Capability | Provided by | How the Agent sees it | When to use |
|
||||
|------------|-------------|-----------------------|-------------|
|
||||
| Sandbox | Box Runtime | The six tools `exec/read/write/edit/glob/grep` are attached directly | Agent needs to run code or read/write files |
|
||||
| Skills | Box Runtime skill store | After the Agent calls `activate`, instructions are injected via Tool Result | Hand the Agent a workflow, template, or script, triggered on demand |
|
||||
| MCP Server | LangBot MCP Loader (stdio mode is hosted by Box) | Tools land directly in the Agent's tool list | Connect an existing MCP service |
|
||||
| Plugin | Plugin Runtime | Capabilities are exposed through the plugin system | Long-lived capability with a config page, event listeners, or knowledge components |
|
||||
|
||||
## Pipeline Binding
|
||||
|
||||
Skills, MCP Servers, and plugins are all **pipeline extensions**. After installing or creating them in the WebUI, the pipeline extension config still decides where they're enabled:
|
||||
|
||||
- Enable all extensions, or
|
||||
- Bind only specific extensions
|
||||
|
||||
Skill binding decides **which skills the Agent can see** (it controls the `<available_skills>` list). The actual skill content is only injected after the Agent calls `activate`.
|
||||
|
||||
## Troubleshooting Map
|
||||
|
||||
| Symptom | Check first |
|
||||
|---------|-------------|
|
||||
| Agent has no `exec/read/write` tools | `box.enabled`, backend availability, and whether the pipeline uses the built-in Agent |
|
||||
| Skill list is empty | Box Runtime status, `box.local.skills_root`, pipeline binding |
|
||||
| stdio MCP fails to start | Box Runtime status, MCP command and environment variables, startup timeout |
|
||||
| Sandbox fails to start in Docker deployment | Whether `langbot_box` mounts `docker.sock`, and whether Box root paths match |
|
||||
| File read/write fails | `box.local.host_root`, `box.local.allowed_mount_roots` |
|
||||
| Backend selection has no effect | Confirm `BOX__BACKEND` is set on the `langbot` service, not on `langbot_box` |
|
||||
|
||||
<Note>
|
||||
Sandbox built-in tools and Skills currently target the built-in Agent. External runners (Dify, n8n, Langflow, Coze, etc.) should use their own tools and execution model.
|
||||
</Note>
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: "Skills"
|
||||
---
|
||||
|
||||
A Skill is an **on-demand instruction bundle**: when the user's request matches, the Agent calls the `activate` tool to pull the skill's instructions into context, then follows them. Skills that aren't activated don't consume context.
|
||||
|
||||
Use Skills to give the Agent a **specialized workflow, template, or script** — "analyze a Python project", "fill a PDF form", "code review" — instead of stuffing every prompt into the System Prompt.
|
||||
|
||||
## How Skills Compare to Plugins and MCP
|
||||
|
||||
| What you want to do | Use this |
|
||||
|---------------------|----------|
|
||||
| A workflow triggered on demand (optional scripts and templates) | Skill |
|
||||
| Connect an existing MCP tool service | MCP Server |
|
||||
| Long-lived capability with config page, events, knowledge base | Plugin |
|
||||
|
||||
See [Runtimes and Extensions](../sandbox/runtime-relationships) for the full picture.
|
||||
|
||||
## Installing Skills
|
||||
|
||||
<Note>
|
||||
Skills require the sandbox. `box.enabled` must be `true` and at least one backend (Docker / Nsjail / E2B) must be available — otherwise you can't install, activate, or edit skills. See [Sandbox Configuration](../sandbox/config).
|
||||
</Note>
|
||||
|
||||
### From LangBot Space (Preferred)
|
||||
|
||||
[LangBot Space](https://space.langbot.app) is the official LangBot marketplace, with a curated list of ready-to-use skills. In the WebUI Skills page, browse and install them with one click — no need to write a `SKILL.md` or prepare any resource files.
|
||||
|
||||
This covers most cases. For custom workflows, use the option below.
|
||||
|
||||
### Create Your Own
|
||||
|
||||
**WebUI** — create, upload a zip, or import from GitHub on the Skills page.
|
||||
|
||||
**Sandbox + `register_skill`**:
|
||||
1. Prepare the directory and `SKILL.md` under the sandbox `/workspace`
|
||||
2. Have the Agent call `register_skill(path="/workspace/my-skill")`
|
||||
|
||||
Both options write to the skill store managed by Box Runtime.
|
||||
|
||||
## Enabling in a Pipeline
|
||||
|
||||
Once a skill is installed, the pipeline extension config decides which skills the Agent can see:
|
||||
|
||||
- Enable "all skills", or
|
||||
- Bind only specific skills
|
||||
|
||||
Binding only affects the `<available_skills>` list (what the Agent can choose from). The full instructions are always injected only after `activate` is called.
|
||||
|
||||
## Writing a SKILL.md
|
||||
|
||||
A skill is a directory plus a `SKILL.md`. The frontmatter holds metadata; the body is what the Agent receives after activation:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
display_name: Code Review Assistant
|
||||
description: Reviews code and gives improvement suggestions; triggered when the user mentions review, code review, or code improvement
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
1. Use `read` to browse the relevant files
|
||||
2. Check readability, potential bugs, and security issues
|
||||
3. Provide improvement suggestions, sorted by priority
|
||||
```
|
||||
|
||||
LangBot currently reads these three fields:
|
||||
|
||||
| Field | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| `name` | When creating/registering | Unique ID, 1–64 chars |
|
||||
| `description` | Strongly recommended | The Agent uses this to decide when to activate — the more specific, the better |
|
||||
| `display_name` | No | Shown in the UI |
|
||||
|
||||
`description` is the Agent's only signal for picking a skill. Make it concrete about **what it does, when it applies, and what trigger words to watch for**.
|
||||
|
||||
For the full spec see [agentskills.io](https://agentskills.io/home). Other fields (`license`, `metadata`, ...) can stay in the file for future compatibility but are not currently read.
|
||||
|
||||
**Skills with resources** place `scripts/`, `templates/`, etc. next to `SKILL.md`. After activation the Agent accesses them at `/workspace/.skills/{skill-name}/`.
|
||||
|
||||
### Tools the Agent Sees
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `activate` | Called automatically by the Agent when it sees a match — pulls SKILL.md into context |
|
||||
| `register_skill` | Registers a directory prepared in the sandbox as a new skill |
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Symptom | What to check |
|
||||
|---------|---------------|
|
||||
| Skill list is empty | `box.enabled`, Box Runtime status, `box.local.skills_root` |
|
||||
| Agent doesn't activate a skill | Whether `description` is specific, whether the pipeline has the skill bound, whether the model supports function calling |
|
||||
| Files missing after activation | Files must live inside the Skill package; the path is `/workspace/.skills/{skill-name}/` |
|
||||
| `register_skill` errors | The path must be under `/workspace`, and the directory or subdirectories within two levels must contain `SKILL.md` |
|
||||
|
||||
<Note>
|
||||
Skills currently target the built-in Agent and depend on function calling plus a sandbox backend. External runners (Dify, n8n, Langflow, Coze, etc.) should use their platform's equivalent mechanism.
|
||||
</Note>
|
||||
@@ -19,16 +19,60 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
コンテナを起動します:
|
||||
推奨の `all` profile でコンテナを起動します。これにより、サンドボックス、stdio MCP ホスティング、Skill の追加/編集など Box Runtime に依存する機能がデフォルトで有効になります:
|
||||
|
||||
```bash
|
||||
docker compose --profile all up
|
||||
```
|
||||
|
||||
これにより `langbot`、`langbot_plugin_runtime`、`langbot_box` が起動します。Box Runtime を有効にせず、基本サービスのみを使う場合は次を実行します：
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
|
||||
`langbot_box` はホスト Docker socket 経由でサンドボックスコンテナを作成するため、Box root のホスト側パスとコンテナ内パスは同一である必要があります：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot:
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__DEFAULT_WORKSPACE=default
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
|
||||
langbot_box:
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Box コントロールプレーンの起動方式はデプロイ方法によって異なります。** Docker デプロイでは独立した `langbot_box` **コンテナ**として動作し、`langbot` は WebSocket（`ws://langbot_box:5410`）で接続します。手動起動 / `uvx` デプロイでは、`langbot` が Box コントロールプレーンとして stdio サブプロセスを直接起動します。`langbot_box` はマウントされた `docker.sock` を介してホスト Docker 上にサンドボックスの兄弟コンテナを作成します。LangBot イメージには `docker` クライアントが同梱されているため、追加のインストールは不要です。
|
||||
</Note>
|
||||
|
||||
`No sandbox backend (Docker/nsjail/E2B) is ready` と表示される場合は、まず現在のユーザーが Docker にアクセスできるか確認してください:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
docker info
|
||||
```
|
||||
|
||||
`docker info` が正常に出力される場合は、LangBot を再起動してください。
|
||||
|
||||
<Warning>
|
||||
`langbot_box` は `LANGBOT_BOX_*` や `BOX__*` 環境変数を直接読み取りません。`BOX__LOCAL__*` は `langbot` に設定し、LangBot が INIT RPC 経由で Box Runtime に渡します。Box root を変更する場合は `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up` のように絶対パスを指定してください。
|
||||
</Warning>
|
||||
|
||||
コンテナはWebUIアクセス用にポート`5300`をマッピングします。`http://127.0.0.1:5300`にアクセスしてWebUIを表示できます。
|
||||
また、メッセージプラットフォームアダプター用に予約されたポート`2280-2290`もマッピングします。
|
||||
また、メッセージプラットフォームアダプター用に予約されたポート`2280-2285`もマッピングします。
|
||||
|
||||
LangBotのデプロイ完了後、引き続き以下をお読みください:
|
||||
|
||||
- [ボット設定ドキュメント](/en/deploy/platforms/readme)
|
||||
- [モデル設定ドキュメント](/en/deploy/models/readme)
|
||||
- [ボット設定ドキュメント](/ja/usage/platforms/readme)
|
||||
- [モデル設定ドキュメント](/ja/usage/models/readme)
|
||||
- [サンドボックスドキュメント](/ja/usage/sandbox/readme)
|
||||
- [Skills ドキュメント](/ja/usage/skills/readme)
|
||||
|
||||
@@ -40,4 +40,4 @@ uv run main.py
|
||||
...
|
||||
```
|
||||
|
||||
Ctrl+Cでプログラムを終了し、[ボットのデプロイ](/en/deploy/platforms/readme)ページに進んでください。
|
||||
Ctrl+Cでプログラムを終了し、[ボットの設定](/ja/usage/platforms/readme)ページに進んでください。
|
||||
|
||||
@@ -42,4 +42,4 @@ title: "1Panelデプロイ"
|
||||
|
||||
その後、ビジュアルインターフェースでLangBotを設定できます。
|
||||
|
||||
次に、[メッセージプラットフォームのデプロイ](/en/deploy/platforms/readme)ページを引き続きお読みください。
|
||||
次に、[メッセージプラットフォームの設定](/ja/usage/platforms/readme)ページを引き続きお読みください。
|
||||
|
||||
@@ -51,4 +51,4 @@ WebUI設定ページ(ビジュアル設定ページ)の外部および内部ア
|
||||
|
||||
JSON設定ファイルを直接変更したい場合は、上の画像に示されているローカルマッピングディレクトリを参照できます。インストールディレクトリに移動すると、`data`フォルダは設定ファイルの保存に使用され、`plugins`フォルダはプラグイン関連ファイルに使用されます。
|
||||
|
||||
次に、[メッセージプラットフォームのデプロイ](/en/deploy/platforms/readme)ページを引き続きお読みください。
|
||||
次に、[メッセージプラットフォームの設定](/ja/usage/platforms/readme)ページを引き続きお読みください。
|
||||
|
||||
@@ -112,6 +112,24 @@ monitoring:
|
||||
check_interval_hours: 1
|
||||
# 各監視テーブルで 1 回に削除する期限切れ行数
|
||||
delete_batch_size: 1000
|
||||
box:
|
||||
backend: 'local' # 'local' (Docker/nsjail), 'docker', 'nsjail', または 'e2b'。BOX__BACKEND で書き込めます。
|
||||
runtime:
|
||||
endpoint: '' # 外部 Box Runtime ベース URL（例: 'ws://127.0.0.1:5410'）。空の場合はローカル自動管理ランタイムを使用。
|
||||
local:
|
||||
profile: 'default'
|
||||
image: '' # カスタムローカルサンドボックスイメージ。空の場合はプロファイルデフォルトを使用。
|
||||
host_root: './data/box' # ローカルワークスペースマウント用のホストルートディレクトリ。Docker デプロイ時は langbot_box にマウントする絶対ホストパスを使用。
|
||||
default_workspace: '' # デフォルトは '<host_root>/default'。
|
||||
skills_root: 'skills' # Box が管理する Skill パッケージディレクトリ。相対パスは host_root 配下に解決されます。
|
||||
allowed_mount_roots: # 空の場合はデフォルトで ['<host_root>']。
|
||||
- './data/box'
|
||||
- '/tmp'
|
||||
workspace_quota_mb: null # オプションのディスククォータオーバーライド (>= 0)。null = プロファイルデフォルト。
|
||||
e2b:
|
||||
api_key: '' # E2B_API_KEY 環境変数でも設定可能。
|
||||
api_url: '' # セルフホストデプロイ用のカスタム API URL。
|
||||
template: '' # デフォルトテンプレート ID（例: 'base', 'python-3.11'）。
|
||||
space:
|
||||
# Space サービス URL
|
||||
url: 'https://space.langbot.app'
|
||||
@@ -142,5 +160,12 @@ space:
|
||||
- `STORAGE__CLEANUP__LOG_RETENTION_DAYS` は `storage.cleanup.log_retention_days` を表します
|
||||
- `MONITORING__AUTO_CLEANUP__RETENTION_DAYS` は `monitoring.auto_cleanup.retention_days` を表します
|
||||
- `PLUGIN__BINARY_STORAGE__MAX_VALUE_BYTES` は `plugin.binary_storage.max_value_bytes` を表します
|
||||
- `BOX__BACKEND` は `box.backend` を表します
|
||||
- `BOX__LOCAL__HOST_ROOT` は `box.local.host_root` を表します
|
||||
- `BOX__LOCAL__SKILLS_ROOT` は `box.local.skills_root` を表します
|
||||
|
||||
起動時、LangBot はすべての環境変数を読み取り、対応する設定を `config.yaml` に適用して `data/config.yaml` ファイルに書き込みます。
|
||||
|
||||
<Note>
|
||||
Box 関連設定は `langbot` サービスに統一形式の `BOX__*` 環境変数で設定します。LangBot は起動時にそれらを `data/config.yaml` に適用し、INIT RPC 経由で Box 設定を `langbot_box` に渡します。`LANGBOT_BOX_*` や `BOX__*` を `langbot_box` に設定しても直接読み取られません。
|
||||
</Note>
|
||||
|
||||
@@ -34,12 +34,12 @@ LangBotは、オープンソースの大規模言語モデル(LLM)ネイティ
|
||||
|
||||
### 2. ボットを設定する
|
||||
|
||||
左サイドバーの[ボットの設定](/en/deploy/platforms/readme)を確認してください
|
||||
左サイドバーの[ボットの設定](/ja/usage/platforms/readme)を確認してください
|
||||
|
||||
### 3. モデルを設定する
|
||||
|
||||
左サイドバーの[対話モデルの設定](/en/deploy/models/readme)を確認してください
|
||||
左サイドバーの[対話モデルの設定](/ja/usage/models/readme)を確認してください
|
||||
|
||||
<br />
|
||||
|
||||
上記の2つのステップを完了すると、LangBotの使用を開始できます。さらに多くの機能を設定する必要がある場合は、[Pipeline](/en/deploy/pipelines/readme)セクションで設定できます
|
||||
上記の2つのステップを完了すると、LangBotの使用を開始できます。さらに多くの機能を設定する必要がある場合は、[Pipeline](/ja/usage/pipelines/readme)セクションで設定できます
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "ナレッジベースの使用"
|
||||
title: "ナレッジベース"
|
||||
---
|
||||
|
||||
LangBotはRAG（Retrieval-Augmented Generation）をネイティブサポートしています。ナレッジベースを作成してパイプラインにバインドすることで、ナレッジベースの内容に基づいて質問に答えることができます。
|
||||
|
||||
+87
-21
@@ -1,41 +1,107 @@
|
||||
---
|
||||
title: "MCPサーバーの使用"
|
||||
title: "MCP サーバー"
|
||||
---
|
||||
|
||||
LangBot は MCP サーバー由来のツールを利用できます。MCP サーバーを追加すれば、ツール使用を有効にしたモデルを持つ組み込み Agent が会話中にそのツールを呼び出せます。
|
||||
|
||||
LangBotはMCPサーバーをサポートしています。MCPサーバーを追加して、大規模言語モデルのツール呼び出し機能を活用し、LLMリクエストをより適切に処理できます。
|
||||
<Info title="MCP は Streamable HTTP、SSE、stdio の 3 モードに対応しています。">
|
||||
まずは [LangBot Space](https://space.langbot.app) からのインストールを推奨します。掲載されている MCP サーバーは設定済みで、そのまま使えます。
|
||||
|
||||
<Info title="- MCP サービスは HTTP Streamable、SSE および stdio モードをサポートしています。">
|
||||
- MCPサーバーの推奨取得チャネル：
|
||||
- [ModelScope](https://modelscope.cn/mcp)
|
||||
- https://mcp.so
|
||||
- https://composio.dev/toolkits
|
||||
[ModelScope](https://modelscope.cn/mcp)、[mcp.so](https://mcp.so)、[composio.dev](https://composio.dev/toolkits) から入手して、後述の手動追加で登録することも可能です。
|
||||
</Info>
|
||||
|
||||
## モデルのFunction Callingを有効化
|
||||
## 3 つの通信モード
|
||||
|
||||
画像に示すように、モデルの`Function Calling`機能を有効にします。
|
||||
| モード | 適した場面 | 備考 |
|
||||
|------|----------|------|
|
||||
| Streamable HTTP (`mode: "http"`) | Streamable HTTP に対応したリモート MCP | LangBot がリモート URL に直接接続 |
|
||||
| SSE | SSE に対応したリモート MCP | LangBot がリモート URL に直接接続 |
|
||||
| stdio | ローカルコマンドで起動する MCP サーバー | Box Runtime が利用可能なときのみサポート |
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp_01.png" alt="enable function call" />
|
||||
<Note>
|
||||
MCP ツールを使うには、パイプラインで**組み込み Agent** を選択し、**ツール使用が有効化されたモデル**を使用する必要があります。[モデル](../models/readme)を参照。Dify、n8n、Langflow、Coze などの外部 Runner は各プラットフォームのツール機構を使います。
|
||||
</Note>
|
||||
|
||||
## MCPサーバーの作成
|
||||
## MCP サーバーをインストール
|
||||
|
||||
`プラグイン管理`をクリックしてから`MCP管理`をクリックします:
|
||||
### LangBot Space から（推奨）
|
||||
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp02.png" alt="server page" />
|
||||
[LangBot Space](https://space.langbot.app) は LangBot 公式のマーケットプレイスで、設定済みの MCP サーバーが多数掲載されています。WebUI の `プラグイン管理` → `MCP 管理` から閲覧して 1 クリックでインストールでき、URL、コマンド、モードなどのパラメータはマーケット側が提供するため、手動入力は不要です。
|
||||
|
||||
右上の`追加`をクリックしてから`MCPサーバーを作成`をクリックします。
|
||||
ほとんどのケースはこれで十分です。掲載されていないサービスを利用する場合は、下記の手動追加を使ってください。
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp03.png" alt="create new mcp server" />
|
||||
### 手動で追加
|
||||
|
||||
例えば、Fetch HTMLサーバーを使用するには、対応するURLを入力し、`テスト`をクリックしてMCPサーバーをテストし、`送信`をクリックしてサーバーを追加します。
|
||||
`プラグイン管理` → `MCP 管理` を開きます：
|
||||
|
||||
追加後、カードのスイッチをクリックしてMCPサーバーに接続します。カードをクリックしてMCPサーバーの詳細を表示します:
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp02.png" alt="MCP 管理ページ" />
|
||||
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp05.png" alt="detailed server" />
|
||||
右上の `追加` → `MCP サーバーを追加` をクリック。URL（HTTP/SSE）またはコマンド（stdio）を入力し、`テスト` で接続を確認、`送信` で保存します：
|
||||
|
||||
## 効果
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp03.png" alt="MCP サーバー作成" />
|
||||
|
||||
パイプライン設定で`Local Agent`をランナーとして選択し、function callingをサポートするモデルを使用する必要があります。
|
||||
保存後、カードのスイッチをオンにして接続します。カードをクリックすると詳細を確認できます：
|
||||
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp04.png" alt="dialog with mcp" />
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp05.png" alt="MCP サーバー詳細" />
|
||||
|
||||
## パイプラインで有効化
|
||||
|
||||
MCP サーバーを追加したあと、パイプライン拡張設定で Agent から見える MCP を決めます：
|
||||
|
||||
- 「すべての MCP サーバーを有効化」をオン、または
|
||||
- 指定した MCP サーバーのみをバインド
|
||||
|
||||
バインドしていない MCP のツールはそのパイプラインのツール一覧に入りません。
|
||||
|
||||
## 高度な設定：stdio MCP
|
||||
|
||||
stdio MCP は Box Runtime によってホストされます。接続前に LangBot は以下を行います：
|
||||
|
||||
1. 共有の MCP Box session を作成または再利用
|
||||
2. コマンドからローカルプロジェクトのパスを推測できれば、プロジェクトをワークスペースに staging
|
||||
3. プロジェクトに `requirements.txt`、`pyproject.toml`、`setup.py`、`setup.cfg` がある場合は依存をインストール
|
||||
4. WebSocket relay 経由で MCP プロセスの stdin/stdout に接続
|
||||
|
||||
マウント、ネットワーク、タイムアウトを細かく調整したい場合、MCP 設定の `extra_args` に `box` オーバーライドを追加できます：
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "stdio",
|
||||
"extra_args": {
|
||||
"command": "python",
|
||||
"args": ["server.py"],
|
||||
"env": {},
|
||||
"box": {
|
||||
"host_path": "/path/to/mcp-project",
|
||||
"network": "on",
|
||||
"host_path_mode": "ro",
|
||||
"startup_timeout_sec": 120,
|
||||
"image": "python:3.11-slim"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
主なフィールド：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| `host_path` | ホスト上の MCP プロジェクトディレクトリ。`box.local.allowed_mount_roots` の許可範囲内である必要があります |
|
||||
| `network` | ネットワークを許可するか（依存インストールでよく使う） |
|
||||
| `host_path_mode` | `host_path` を staging するときのアクセスモード。デフォルトは `ro`。stdio MCP は通常ワークスペースに staging されます |
|
||||
| `startup_timeout_sec` | Box 準備と依存インストールのタイムアウト、デフォルト 120 秒。接続待ちで約 30 秒追加されます |
|
||||
| `image` | Docker バックエンドで使用するランタイムイメージ |
|
||||
|
||||
<Warning>
|
||||
stdio MCP は Box 内で実行されます。依存インストールとプロセス起動は sandbox profile、ネットワーク権限、リソース制限、マウント許可リストの影響を受けます。
|
||||
</Warning>
|
||||
|
||||
## よくある問題
|
||||
|
||||
| 症状 | 確認項目 |
|
||||
|------|--------|
|
||||
| MCP の接続に失敗 | URL、コマンド、引数、環境変数が正しいか |
|
||||
| stdio MCP が接続中のまま | Box Runtime の状態、`startup_timeout_sec` が短すぎないか |
|
||||
| 依存インストールに失敗 | sandbox がネットワークを許可しているか、依存ファイルが正しいか |
|
||||
| ローカルファイルにアクセスできない | `host_path` が存在し、`allowed_mount_roots` 内にあるか |
|
||||
| Agent が MCP ツールを認識しない | パイプラインで組み込み Agent を使っているか、モデルでツール使用を有効にしているか、MCP がパイプラインにバインドされているか |
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "モデルの設定(Models)"
|
||||
title: "モデル (Models)"
|
||||
---
|
||||
|
||||
## LangBot Models
|
||||
@@ -26,11 +26,16 @@ LangBot Modelsは、LangBotが公式に提供するモデルサービスです
|
||||
|
||||
これら4つのパラメータを入力します: `モデル名`、`モデルプロバイダー`、`リクエストURL`、`APIキー`、そして送信します。
|
||||
|
||||
モデルの機能については、特定のモデルの特性に応じて選択してください:
|
||||
モデルの機能は、ベースモデルが実際にサポートしているものを有効化します：
|
||||
|
||||
- ビジュアル機能: 画像を認識するために有効にする必要があります
|
||||
- **ビジョン**：有効にすると画像を認識可能
|
||||
- **ツール使用**（function calling / tool use）：有効にすると LLM が会話中にツールを呼び出せる
|
||||
|
||||
- Function Calling: 会話でAgentツールを使用するために有効にする必要があります
|
||||
<Note>
|
||||
**MCP サーバー、サンドボックスの組み込みツール（`exec`/`read`/`write`/`edit`/`glob`/`grep`）、Skills のいずれかを利用したい場合は、モデルでツール使用を必ず有効にしてください。** 有効でなければ、パイプラインで拡張機能をバインドしていても Agent はツールを呼び出しません。
|
||||
|
||||
ベースモデル自体が function calling に対応している必要があります。不明な場合はモデル提供元のドキュメントを確認してください。
|
||||
</Note>
|
||||
|
||||
### 埋め込みモデル (Embedding Model)
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "対話パイプライン設定の変更(Pipelines)"
|
||||
title: "対話パイプライン (Pipelines)"
|
||||
---
|
||||
|
||||
パイプラインは、メッセージを受信した後の処理フローと、大規模言語モデルとの情報交換を制御します。各ボットは1つのパイプラインにバインドでき、同じパイプラインは複数のボットにバインドできます。
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "サンドボックス設定"
|
||||
---
|
||||
|
||||
サンドボックス設定は LangBot メインプロセスが管理し、Box Runtime が実際の実行を担当します。通常のデプロイでは、バックエンド、ワークスペースディレクトリ、セキュリティプロファイルだけを決めれば十分です。
|
||||
|
||||
<Note>
|
||||
このページの `box.*` 設定はすべて `data/config.yaml` に記述します。ファイルの場所と読み込みの仕組みは[システム環境設定](../../deploy/settings)を参照してください。
|
||||
</Note>
|
||||
|
||||
## 推奨設定
|
||||
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local' # Docker / Nsjail から利用可能なものを自動選択
|
||||
local:
|
||||
profile: 'default'
|
||||
host_root: './data/box'
|
||||
skills_root: 'skills'
|
||||
```
|
||||
|
||||
- `enabled`：サンドボックスのマスタースイッチ。`false` にすると、サンドボックス組み込みツール、Skill の追加 / 編集、stdio MCP のホスティングなど Box 依存の機能はすべて無効になります。
|
||||
- `backend`：下記「バックエンドの選択」を参照。
|
||||
- `local.profile`：セキュリティプロファイル。ネットワーク、マウント、リソース制限を制御。
|
||||
- `local.host_root`：ホスト側のサンドボックス作業ディレクトリ。サンドボックス内では `/workspace` にマウントされます。
|
||||
- `local.skills_root`：Skill パッケージのディレクトリ。相対パスは `host_root` 配下に解決され、デフォルトは `host_root/skills`。
|
||||
|
||||
<Note>
|
||||
Skill は Box Runtime が管理する skill store からのみ読み込まれます。Box Runtime またはバックエンドが利用できない場合、Skill 一覧は空になり、追加 / 編集 / `register_skill` も使えません。`data/skills/` へのフォールバックは行いません。
|
||||
</Note>
|
||||
|
||||
## バックエンドの選択
|
||||
|
||||
サンドボックスは**ローカルコンテナ**または**クラウド**で動作させられます。`box.backend` でどちらを使うかを指定します：
|
||||
|
||||
| `backend` | 実行場所 | 動作 |
|
||||
|-----------|---------|------|
|
||||
| `local`（既定） | ローカルコンテナ | Docker / Nsjail から利用可能なものを自動選択（Docker 優先） |
|
||||
| `docker` | ローカルコンテナ | Docker を強制使用。Docker daemon が必要 |
|
||||
| `nsjail` | ローカルコンテナ | Nsjail を強制使用（Linux のみ）。カスタムイメージ非対応 |
|
||||
| `e2b` | クラウド | [E2B](https://e2b.dev) クラウドサンドボックスを使用。API キーが必要 |
|
||||
|
||||
`local` は「自動選択」のショートハンドであり、`docker` / `nsjail` と並列の 4 つ目のバックエンドではありません。ローカル系バックエンド（`local` / `docker` / `nsjail`）は `box.local.*` 設定セクションを**共有**し、クラウドバックエンドは `box.e2b.*` を使います。
|
||||
|
||||
<Note>
|
||||
`backend` は強制値です。`docker` を指定して Docker が使えない場合、Nsjail や E2B に**自動でフォールバックしません**。自動 fan-out するのは `local` だけです。
|
||||
|
||||
環境変数 `BOX__BACKEND` で `box.backend` を上書きできます（`config.yaml` より優先）。
|
||||
</Note>
|
||||
|
||||
## セキュリティプロファイル
|
||||
|
||||
`box.local.profile` はローカル系バックエンドのネットワーク、マウント、リソース制限を制御します：
|
||||
|
||||
| Profile | ネットワーク | マウント | リソース | 推奨シーン |
|
||||
|---------|---------|---------|---------|----------|
|
||||
| `default` | オフ | 読み書き | 既定制限 | 既定の選択 |
|
||||
| `offline_readonly` | オフ | 読み取り専用 | より厳格 | 信頼できないファイルの読み込み |
|
||||
| `network_basic` | 基本ネットワーク | 読み書き | 既定制限 | API アクセス、依存関係インストール |
|
||||
| `network_extended` | フルネットワーク | 読み書き | 緩和 | 開発、デバッグ、複雑なタスク |
|
||||
|
||||
最小権限を優先：ネットワークが不要なら `default` または `offline_readonly`；`allowed_mount_roots` には必要なディレクトリのみを追加。
|
||||
|
||||
## ローカル系バックエンド設定（box.local.*）
|
||||
|
||||
ローカル系バックエンド（`local` / `docker` / `nsjail`）は以下を共有します：
|
||||
|
||||
| 設定項目 | 既定値 | 説明 |
|
||||
|---------|--------|------|
|
||||
| `local.profile` | `default` | 上記「セキュリティプロファイル」を参照 |
|
||||
| `local.image` | 空 | Docker バックエンドのカスタムイメージ。空 = プロファイル既定を使用 |
|
||||
| `local.host_root` | `./data/box` | ホスト作業ディレクトリのベース。サンドボックス内の `/workspace` にマップ |
|
||||
| `local.default_workspace` | 空 | 既定ワークスペース名。空 = `<host_root>/default` |
|
||||
| `local.skills_root` | `skills` | Skill パッケージディレクトリ。相対パスは `host_root` 配下に解決 |
|
||||
| `local.allowed_mount_roots` | `[host_root]` | Agent がマウント要求できるホストディレクトリの許可リスト |
|
||||
| `local.workspace_quota_mb` | `null` | ワークスペースのディスク配額（MB）。`null` = プロファイル既定 |
|
||||
|
||||
## クラウドバックエンド設定（box.e2b.*）
|
||||
|
||||
`backend: 'e2b'` を指定したうえで設定します：
|
||||
|
||||
| 設定項目 | 既定値 | 説明 |
|
||||
|---------|--------|------|
|
||||
| `e2b.api_key` | 空 | E2B API キー。環境変数 `E2B_API_KEY` でも設定可 |
|
||||
| `e2b.api_url` | 空 | セルフホスト E2B のエンドポイント。環境変数 `E2B_API_URL` でも設定可 |
|
||||
| `e2b.template` | 空 | 既定の E2B テンプレート ID |
|
||||
|
||||
E2B はホスト側に Docker や Nsjail を必要とせず、毎回の実行をリモートサンドボックスで行います。
|
||||
|
||||
## Docker Compose デプロイ
|
||||
|
||||
Docker Compose では、サンドボックス設定は `langbot` サービス側に記述します。LangBot は起動時に INIT RPC で設定を `langbot_box` に転送します。
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot_box:
|
||||
image: rockchin/langbot:latest
|
||||
container_name: langbot_box
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]
|
||||
|
||||
langbot:
|
||||
image: rockchin/langbot:latest
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`langbot_box` は Docker daemon にアクセスします。`docker.sock` のマウントは信頼できる環境でのみ行い、Box のルートパスをホストと `langbot_box` コンテナ内で一致させてください。
|
||||
</Warning>
|
||||
|
||||
外部の Box Runtime（リモートホストなど）に接続する場合は `box.runtime.endpoint` で URL を指定します：
|
||||
|
||||
```yaml
|
||||
box:
|
||||
runtime:
|
||||
endpoint: 'ws://192.168.1.10:5410'
|
||||
```
|
||||
|
||||
## 環境変数
|
||||
|
||||
| 環境変数 | 対応する設定 |
|
||||
|----------|----------|
|
||||
| `BOX__ENABLED` | `box.enabled` |
|
||||
| `BOX__BACKEND` | `box.backend` |
|
||||
| `BOX__LOCAL__PROFILE` | `box.local.profile` |
|
||||
| `BOX__LOCAL__IMAGE` | `box.local.image` |
|
||||
| `BOX__LOCAL__HOST_ROOT` | `box.local.host_root` |
|
||||
| `BOX__LOCAL__DEFAULT_WORKSPACE` | `box.local.default_workspace` |
|
||||
| `BOX__LOCAL__SKILLS_ROOT` | `box.local.skills_root` |
|
||||
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`、カンマ区切り |
|
||||
| `BOX__LOCAL__WORKSPACE_QUOTA_MB` | `box.local.workspace_quota_mb` |
|
||||
| `BOX__E2B__API_KEY` | `box.e2b.api_key` |
|
||||
| `BOX__E2B__API_URL` | `box.e2b.api_url` |
|
||||
| `BOX__E2B__TEMPLATE` | `box.e2b.template` |
|
||||
|
||||
<Note>
|
||||
`langbot_box` サービス側には `BOX__*` や `LANGBOT_BOX_*` を設定しないでください。Box Runtime はこれらを直接読みません——設定は LangBot から INIT RPC 経由で渡されます。
|
||||
</Note>
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: "サンドボックス (Sandbox)"
|
||||
---
|
||||
|
||||
サンドボックスは組み込み Agent に隔離された実行環境を提供します。コマンドの実行、ファイルの読み書き、長期常駐プロセスの実行が可能です。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。
|
||||
|
||||
サンドボックスを有効化すると、組み込み Agent は自動的に 6 つのツールを取得します。パイプラインで個別に有効化する必要はありません。
|
||||
|
||||
## 組み込みツール
|
||||
|
||||
| ツール | 用途 |
|
||||
|------|------|
|
||||
| `exec` | サンドボックス内で Shell コマンドを実行 |
|
||||
| `read` | ワークスペースのファイルを読み取る |
|
||||
| `write` | ファイルを作成または上書き |
|
||||
| `edit` | 文字列置換でファイルを編集 |
|
||||
| `glob` | glob パターンでファイルを検索 |
|
||||
| `grep` | 正規表現でファイル内容を検索 |
|
||||
|
||||
`exec` はサンドボックスコンテナ内で実行されます。残り 5 つはホスト側の `/workspace` にマッピングされたディレクトリを直接読み書きします。
|
||||
|
||||
<Note>
|
||||
これらのツールは組み込み Agent 向けです。Dify、n8n、Langflow、Coze などの外部 Runner を使用する場合は、各プラットフォーム独自のツール機構を利用してください。
|
||||
</Note>
|
||||
|
||||
## サンドボックススコープ
|
||||
|
||||
パイプラインの AI 設定で、メッセージ間でサンドボックスをどのように共有するかを選べます。デフォルトの「チャットごと」で多くのシナリオに対応できます。
|
||||
|
||||
| スコープ | テンプレート | 共有範囲 |
|
||||
|--------|------|---------|
|
||||
| グローバル | `{global}` | 全ユーザーが 1 つのサンドボックスを共有 |
|
||||
| チャットごと（デフォルト） | `{launcher_type}_{launcher_id}` | 同じグループ／個人チャットで共有 |
|
||||
| ユーザーごと | `{launcher_type}_{launcher_id}_{sender_id}` | グループ内の各メンバーが独立 |
|
||||
| 会話ごと | `{launcher_type}_{launcher_id}_{conversation_id}` | 会話単位で隔離 |
|
||||
| メッセージごと | `{query_id}` | 完全にステートレス |
|
||||
|
||||
<Warning>
|
||||
同一スコープ内のコマンドはファイルシステム状態を共有します。完全な隔離が必要な場合は「メッセージごと」を選択してください。
|
||||
</Warning>
|
||||
|
||||
## ライフサイクル
|
||||
|
||||
| 状況 | 動作 |
|
||||
|------|------|
|
||||
| 5 分以上アイドル | 自動クリーンアップ |
|
||||
| Box がホストするプロセス（stdio MCP など）が稼働中 | クリーンアップしない。プロセス終了後に解放 |
|
||||
| `persistent: true` 設定時 | 自動クリーンアップなし |
|
||||
|
||||
## クイックスタート
|
||||
|
||||
1. **バックエンドの準備**: ローカルに Docker をインストール、または Nsjail / E2B を選択
|
||||
2. **`config.yaml` に記述**:
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local'
|
||||
local:
|
||||
host_root: './data/box'
|
||||
```
|
||||
3. **LangBot を起動**: サンドボックスは自動的に有効化
|
||||
4. **パイプラインで** 組み込み Agent と関数呼び出し対応モデルを選択
|
||||
|
||||
その後、Agent は自動的に 6 つのツールを取得します。詳細な設定は [サンドボックス設定](./config) を参照してください。
|
||||
|
||||
## サンドボックスを無効化する
|
||||
|
||||
`box.enabled: false` を設定します。サンドボックスに依存するすべての機能（組み込みツール、Skill の作成／編集／起動、stdio MCP）が同時に無効になります。http/sse モードの MCP は影響を受けません。
|
||||
|
||||
## 次のステップ
|
||||
|
||||
- [サンドボックス設定](./config) — バックエンド、セキュリティプリセット、マウント、環境変数
|
||||
- [ランタイムと拡張機能の関係](./runtime-relationships) — サンドボックス、Skills、MCP、プラグインの役割分担
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "ランタイムと拡張機能の関係"
|
||||
---
|
||||
|
||||
LangBot には **プラグイン、MCP、Skills、サンドボックス** という 4 種類の拡張機構が併存しており、混同されやすい部分です。本ページではそれぞれの役割と使い分けを整理します。
|
||||
|
||||
## 一行で区別する
|
||||
|
||||
- **サンドボックス**: 実行環境。Agent がコマンド実行やファイル読み書きを行う場所
|
||||
- **Skills**: オンデマンドで起動する指示パック。Agent に一時的に専門的なワークフローを追加する
|
||||
- **MCP サーバー**: 外部のツールサービスに接続する
|
||||
- **プラグイン**: 長期常駐する拡張プロセス。設定ページ、イベント監視、ナレッジベースを持てる
|
||||
|
||||
## 対応表
|
||||
|
||||
| 機能 | 提供元 | Agent への入り方 | いつ使うか |
|
||||
|------|--------|----------------|---------|
|
||||
| サンドボックス | Box Runtime | `exec/read/write/edit/glob/grep` の 6 点セットを直接付与 | Agent がコード実行やファイル読み書きを行うとき |
|
||||
| Skills | Box Runtime skill store | Agent が `activate` を呼び出した後、指示が Tool Result として注入される | Agent にワークフロー／テンプレート／スクリプトを追加し、必要時にのみ発火させたいとき |
|
||||
| MCP サーバー | LangBot MCP Loader（stdio モードは Box がホスト） | ツールが利用可能ツール一覧に直接入る | 既存の MCP サービスに接続したいとき |
|
||||
| プラグイン | Plugin Runtime | プラグインシステムから能力が公開される | 長期的な機能、設定ページ／イベント監視／ナレッジコンポーネントが必要なとき |
|
||||
|
||||
## パイプラインへのバインド
|
||||
|
||||
Skills、MCP サーバー、プラグインはすべて **パイプライン拡張** に属します。WebUI でインストール／作成した後、パイプライン拡張設定で有効化範囲を決定する必要があります。
|
||||
|
||||
- すべての拡張を有効化する、または
|
||||
- 指定した拡張のみをバインドする
|
||||
|
||||
Skills のバインドは Agent が **どの Skill を見えるか** を決定します（`<available_skills>` 一覧に影響）。具体的な Skill 内容は Agent が `activate` を呼び出した後にのみ注入されます。
|
||||
|
||||
## トラブルシューティングの入口
|
||||
|
||||
| 症状 | まず確認すること |
|
||||
|------|---------|
|
||||
| Agent に `exec/read/write` ツールがない | `box.enabled`、バックエンドが利用可能か、パイプラインが組み込み Agent を使用しているか |
|
||||
| Skill 一覧が空 | Box Runtime の状態、`box.local.skills_root`、パイプラインのバインド |
|
||||
| stdio MCP の起動に失敗 | Box Runtime の状態、MCP コマンドと環境変数、起動タイムアウト |
|
||||
| Docker デプロイでサンドボックスが起動しない | `langbot_box` が `docker.sock` をマウントしているか、Box ルートディレクトリのパスが一致しているか |
|
||||
| ファイル読み書きに失敗 | `box.local.host_root`、`box.local.allowed_mount_roots` |
|
||||
| バックエンド選択が効かない | `BOX__BACKEND` が `langbot_box` ではなく `langbot` サービスに設定されているか確認 |
|
||||
|
||||
<Note>
|
||||
サンドボックスの組み込みツールと Skills は、現在は組み込み Agent 向けです。外部 Runner（Dify、n8n、Langflow、Coze など）では、各プラットフォーム独自のツールと実行機構を使用してください。
|
||||
</Note>
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: "スキル (Skills)"
|
||||
---
|
||||
|
||||
Skill は**必要時に起動する**指示パックです。ユーザーのリクエストが該当する内容になると、Agent が `activate` ツールを呼び出してその Skill の指示をコンテキストに取り込み、それに従ってタスクを完了させます。起動されていない Skill はコンテキストを消費しません。
|
||||
|
||||
Agent に**専門的なワークフロー、テンプレート、スクリプト**を一つ追加するのに向いています。たとえば「Python プロジェクトの解析」「PDF フォーム入力」「コードレビュー」など。System Prompt に全部詰め込む必要はありません。
|
||||
|
||||
## プラグイン・MCP との違い
|
||||
|
||||
| やりたいこと | 使うもの |
|
||||
|------|------|
|
||||
| 必要時に起動する一連のワークフロー（スクリプトやテンプレート付き可） | Skill |
|
||||
| 既存の MCP ツールサービスに接続 | MCP サーバー |
|
||||
| 長期常駐機能、設定画面、イベント、ナレッジベース | プラグイン |
|
||||
|
||||
詳細は[ランタイムと拡張機能の関係](../sandbox/runtime-relationships)を参照。
|
||||
|
||||
## Skill のインストール
|
||||
|
||||
<Note>
|
||||
Skill はサンドボックスに依存します。`box.enabled` が `true` で、Docker / Nsjail / E2B のいずれかが利用可能なときのみ、Skill のインストール、起動、編集ができます。詳細は[サンドボックス設定](../sandbox/config)を参照。
|
||||
</Note>
|
||||
|
||||
### LangBot Space から（推奨）
|
||||
|
||||
[LangBot Space](https://space.langbot.app) は LangBot 公式のマーケットプレイスで、すぐに使える Skill が多数掲載されています。WebUI の Skills ページから閲覧して 1 クリックでインストールでき、`SKILL.md` の作成やリソースファイルの準備は不要です。
|
||||
|
||||
ほとんどのケースはこれで十分です。独自のワークフローが必要な場合は下記の方法を使ってください。
|
||||
|
||||
### 自分で作る
|
||||
|
||||
**WebUI** — Skills ページで新規作成、zip アップロード、GitHub からのインポートが可能。
|
||||
|
||||
**サンドボックス + `register_skill`**：
|
||||
1. サンドボックスの `/workspace` 配下にディレクトリと `SKILL.md` を準備
|
||||
2. Agent に `register_skill(path="/workspace/my-skill")` を呼び出させる
|
||||
|
||||
いずれの方法でも Box Runtime が管理する skill store に書き込まれます。
|
||||
|
||||
## パイプラインで有効化
|
||||
|
||||
Skill をインストールしたあと、パイプラインの拡張設定で Agent から見える Skill を決めます：
|
||||
|
||||
- 「すべての Skill を有効化」をオンにする、または
|
||||
- 指定した Skill のみをバインドする
|
||||
|
||||
バインドは `<available_skills>` 一覧（Agent が選択肢として認識する対象）にのみ影響します。完全な指示は常に `activate` が呼ばれた後に注入されます。
|
||||
|
||||
## SKILL.md を書く
|
||||
|
||||
Skill はディレクトリと `SKILL.md` 1 つで構成されます。frontmatter にメタデータを書き、本文は Agent が起動後に受け取る指示です：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
display_name: コードレビューアシスタント
|
||||
description: コードをレビューして改善提案を行う。ユーザーが review、レビュー、コード改善に言及したときに起動
|
||||
---
|
||||
|
||||
## 実行手順
|
||||
|
||||
1. `read` で関連ファイルをざっと確認
|
||||
2. 可読性、潜在的なバグ、セキュリティ問題をチェック
|
||||
3. 優先度順に改善提案を提示
|
||||
```
|
||||
|
||||
LangBot は現在、以下の 3 つのフィールドを読み取ります：
|
||||
|
||||
| フィールド | 必須 | 説明 |
|
||||
|------|------|------|
|
||||
| `name` | 作成／登録時 | 一意の識別子、1–64 文字 |
|
||||
| `description` | 強く推奨 | Agent はこれをもとに起動可否を判断する——具体的なほど選ばれやすい |
|
||||
| `display_name` | 任意 | UI 表示名 |
|
||||
|
||||
`description` は Agent が Skill を選ぶ唯一の手がかりです。**機能・適用シーン・想定されるトリガーワード**を具体的に書きましょう。
|
||||
|
||||
完全な仕様は [agentskills.io](https://agentskills.io/home) を参照してください。その他のフィールド（`license`、`metadata` など）は将来の互換のために残せますが、現在は読み取られません。
|
||||
|
||||
**リソースを伴う Skill** では `SKILL.md` と同じ階層に `scripts/`、`templates/` などを置きます。起動後、Agent は `/workspace/.skills/{skill-name}/` でこれらにアクセスできます。
|
||||
|
||||
### Agent が使えるツール
|
||||
|
||||
| ツール | 用途 |
|
||||
|------|------|
|
||||
| `activate` | Agent が該当を判断したときに自動で呼び出し、SKILL.md をコンテキストに取り込む |
|
||||
| `register_skill` | サンドボックスに用意したディレクトリを新しい Skill として登録 |
|
||||
|
||||
## よくある問題
|
||||
|
||||
| 症状 | 確認項目 |
|
||||
|------|--------|
|
||||
| Skill 一覧が空 | `box.enabled`、Box Runtime の状態、`box.local.skills_root` |
|
||||
| Agent が Skill を起動しない | `description` が具体的か、パイプラインでバインドされているか、モデルが関数呼び出しに対応しているか |
|
||||
| 起動後にファイルが見つからない | ファイルは Skill パッケージ内に置く必要があり、パスは `/workspace/.skills/{skill-name}/` |
|
||||
| `register_skill` がエラー | パスは `/workspace` 配下である必要があり、ディレクトリまたは 2 階層以内のサブディレクトリに `SKILL.md` が必要 |
|
||||
|
||||
<Note>
|
||||
Skills は現在、組み込み Agent 向けで、関数呼び出しとサンドボックスバックエンドに依存します。外部 Runner（Dify、n8n、Langflow、Coze など）では各プラットフォームの同等機構を利用してください。
|
||||
</Note>
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"version": 1,
|
||||
"skills": {
|
||||
"writing-skills": {
|
||||
"source": "obra/superpowers",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/writing-skills/SKILL.md",
|
||||
"computedHash": "c0a92e629e39ea91b1f54da67a6aa92723008a8ef5b500c6de078f55485937c7"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -20,23 +20,68 @@ git clone https://github.com/langbot-app/LangBot
|
||||
cd LangBot/docker
|
||||
```
|
||||
|
||||
启动容器：
|
||||
启动容器（推荐启用 `all` profile，以默认启用沙箱、stdio MCP 托管、Skill 添加/编辑等依赖 Box Runtime 的功能）：
|
||||
|
||||
```bash
|
||||
docker compose --profile all up
|
||||
```
|
||||
|
||||
这会启动 `langbot`、`langbot_plugin_runtime` 和 `langbot_box`。如果只需要基础服务，不启用 Box Runtime，可以使用：
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
|
||||
`langbot_box` 通过主机 Docker socket 创建沙箱容器，因此 Box 根目录的宿主机路径和容器内路径必须一致：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot:
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__DEFAULT_WORKSPACE=default
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
|
||||
langbot_box:
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Box 控制面的启动方式因部署方式而异。** 容器部署下，Box 控制面以独立的 `langbot_box` **容器**运行，`langbot` 通过 WebSocket（`ws://langbot_box:5410`）连接它；而手动启动 / `uvx` 部署则由 `langbot` 直接拉起一个 stdio 子进程作为 Box 控制面。`langbot_box` 借助挂载的宿主 `docker.sock` 在宿主 Docker 上创建沙箱兄弟容器，LangBot 镜像已内置 `docker` 客户端，无需额外安装。
|
||||
</Note>
|
||||
|
||||
如果提示 `No sandbox backend (Docker/nsjail/E2B) is ready`，请先确认当前用户可访问 Docker：
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
docker info
|
||||
```
|
||||
|
||||
若 `docker info` 正常输出，请重启 LangBot。
|
||||
|
||||
<Warning>
|
||||
`langbot_box` 不直接读取 `LANGBOT_BOX_*` 或 `BOX__*` 环境变量；Box 配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 传给 Box Runtime。若要改 Box 根目录，请使用绝对路径设置 `LANGBOT_BOX_ROOT`，例如 `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up`。
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
- 如果你的主机位于中国大陆，可以考虑把 `docker-compose.yaml` 文件中的镜像名称改为`docker.langbot.app/langbot-public/rockchin/langbot:latest`以使用我们提供的镜像源。
|
||||
- 推荐[设置 Docker 容器代理](https://docker.github.net.cn/network/proxy/)，以便保证 LangBot 在运行期间的网络访问通畅。
|
||||
- 如果需要禁用或强制沙箱后端，请参考[沙箱配置](/zh/usage/sandbox/config)。
|
||||
</Info>
|
||||
|
||||
首次启动会输出创建配置文件的提示，请继续按照文件配置。
|
||||
|
||||
容器会映射`5300`端口供 WebUI 使用，您可以访问`http://127.0.0.1:5300`查看 WebUI。\
|
||||
还会映射`2280-2290`端口供使用 OneBot 协议的消息平台适配器反向连接。
|
||||
还会映射`2280-2285`端口供使用 OneBot 协议的消息平台适配器反向连接。
|
||||
|
||||
完成 LangBot 部署后，请继续阅读：
|
||||
|
||||
- [配置机器人文档](/zh/deploy/platforms/readme)。
|
||||
- [配置模型文档](/zh/deploy/models/readme)。
|
||||
- [配置机器人文档](/zh/usage/platforms/readme)。
|
||||
- [配置模型文档](/zh/usage/models/readme)。
|
||||
- [沙箱文档](/zh/usage/sandbox/readme)。
|
||||
- [技能系统文档](/zh/usage/skills/readme)。
|
||||
|
||||
@@ -51,4 +51,4 @@ uv run main.py
|
||||
...
|
||||
```
|
||||
|
||||
接下来可以使用 Ctrl+C 退出程序，继续查看[部署机器人](/zh/deploy/platforms/readme)页。
|
||||
接下来可以使用 Ctrl+C 退出程序，继续查看[配置机器人](/zh/usage/platforms/readme)页。
|
||||
|
||||
@@ -46,4 +46,4 @@ title: "1Panel部署"
|
||||
|
||||
然后就可以在可视化界面进行配置了。
|
||||
|
||||
接下来请继续阅读[部署消息平台](/zh/deploy/platforms/readme)页。
|
||||
接下来请继续阅读[配置消息平台](/zh/usage/platforms/readme)页。
|
||||
|
||||
@@ -52,4 +52,4 @@ title: "宝塔面板部署"
|
||||
|
||||
然后就可以在可视化界面进行配置了。
|
||||
|
||||
接下来请继续阅读[部署消息平台](/zh/deploy/platforms/readme)页。
|
||||
接下来请继续阅读[配置消息平台](/zh/usage/platforms/readme)页。
|
||||
|
||||
@@ -112,6 +112,25 @@ monitoring:
|
||||
check_interval_hours: 1
|
||||
# 每个监控表单批删除的过期记录数量
|
||||
delete_batch_size: 1000
|
||||
box:
|
||||
enabled: true # Box Runtime 总开关。false 时禁用沙箱、Skill 添加/编辑和 stdio MCP 等依赖 Box 的功能。
|
||||
backend: 'local' # 'local' (Docker/nsjail), 'docker', 'nsjail', 或 'e2b'。可通过 BOX__BACKEND 写入。
|
||||
runtime:
|
||||
endpoint: '' # 外部 Box Runtime 基础 URL，如 'ws://127.0.0.1:5410'。留空时，非 Docker 部署使用本地自动管理的 Runtime；Docker 部署连接 Compose 网络中的 langbot_box:5410。
|
||||
local:
|
||||
profile: 'default'
|
||||
image: '' # 自定义本地沙箱镜像。留空使用 profile 默认值。
|
||||
host_root: './data/box' # 本地工作区挂载的主机根目录。Docker 部署时应使用可被 langbot_box 挂载的绝对主机路径。
|
||||
default_workspace: '' # 默认为 '<host_root>/default'。
|
||||
skills_root: 'skills' # Box 管理的 Skill 包目录。相对路径会解析到 host_root 下。
|
||||
allowed_mount_roots: # 默认为 ['<host_root>']。
|
||||
- './data/box'
|
||||
- '/tmp'
|
||||
workspace_quota_mb: null # 可选磁盘配额覆盖 (>= 0)。null 表示使用 profile 默认值。
|
||||
e2b:
|
||||
api_key: '' # 也可通过 E2B_API_KEY 环境变量设置。
|
||||
api_url: '' # 自托管部署的自定义 API URL。
|
||||
template: '' # 默认模板 ID（如 'base', 'python-3.11'）。
|
||||
space:
|
||||
# Space 服务 URL
|
||||
url: 'https://space.langbot.app'
|
||||
@@ -142,5 +161,13 @@ space:
|
||||
- `STORAGE__CLEANUP__LOG_RETENTION_DAYS` 代表 `storage.cleanup.log_retention_days`
|
||||
- `MONITORING__AUTO_CLEANUP__RETENTION_DAYS` 代表 `monitoring.auto_cleanup.retention_days`
|
||||
- `PLUGIN__BINARY_STORAGE__MAX_VALUE_BYTES` 代表 `plugin.binary_storage.max_value_bytes`
|
||||
- `BOX__ENABLED` 代表 `box.enabled`
|
||||
- `BOX__BACKEND` 代表 `box.backend`
|
||||
- `BOX__LOCAL__HOST_ROOT` 代表 `box.local.host_root`
|
||||
- `BOX__LOCAL__SKILLS_ROOT` 代表 `box.local.skills_root`
|
||||
|
||||
在启动时，LangBot 会读取所有环境变量，将对应的配置应用到 `config.yaml` 中并写入到 `data/config.yaml` 文件中。
|
||||
|
||||
<Note>
|
||||
Box 相关配置应设置在 `langbot` 服务上，使用统一的 `BOX__*` 环境变量。LangBot 会在启动时写入 `data/config.yaml`，并通过 INIT RPC 将 Box 配置传给 `langbot_box`。不要在 `langbot_box` 服务上设置 `LANGBOT_BOX_*` 或 `BOX__*`，这些变量不会被直接读取。
|
||||
</Note>
|
||||
|
||||
@@ -38,12 +38,12 @@ LangBot 是一个开源的大语言模型（LLM）原生即时通信机器人平
|
||||
|
||||
### 2. 配置机器人
|
||||
|
||||
查看左侧的[配置机器人](/zh/deploy/platforms/readme)
|
||||
查看左侧的[配置机器人](/zh/usage/platforms/readme)
|
||||
|
||||
### 3. 配置模型
|
||||
|
||||
查看左侧[配置对话模型](/zh/deploy/models/readme)
|
||||
查看左侧[配置对话模型](/zh/usage/models/readme)
|
||||
|
||||
<br />
|
||||
|
||||
完成以上两步后即可使用，如果需要更多功能的配置，可在[流水线](/zh/deploy/pipelines/readme)中设置
|
||||
完成以上两步后即可使用，如果需要更多功能的配置，可在[流水线](/zh/usage/pipelines/readme)中设置
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "使用知识库 (Knowledge Base)"
|
||||
title: "知识库 (Knowledge Base)"
|
||||
---
|
||||
|
||||
LangBot 原生支持 RAG（Retrieval-Augmented Generation，即检索增强生成），您可以创建知识库，并将其与流水线绑定，流水线将根据知识库中的内容回答问题。
|
||||
|
||||
+88
-41
@@ -1,60 +1,107 @@
|
||||
---
|
||||
title: "使用MCP服务器"
|
||||
title: "MCP 服务器"
|
||||
---
|
||||
|
||||
LangBot 支持使用来自 MCP 服务器的工具，您可以添加 MCP 服务器，使用大语言模型中的工具调用特性，更好的处理 LLM 请求。
|
||||
LangBot 支持调用来自 MCP 服务器的工具。添加 MCP 后，启用了工具使用能力的内置 Agent 即可在对话中调用这些工具。
|
||||
|
||||
<Info>
|
||||
MCP 服务器推荐获取渠道：
|
||||
- [ModelScope](https://modelscope.cn/mcp)
|
||||
- https://mcp.so
|
||||
- https://composio.dev/toolkits
|
||||
<Info title="MCP 支持 Streamable HTTP、SSE 和 stdio 三种模式。">
|
||||
首选从 [LangBot Space](https://space.langbot.app) 安装：已上架的 MCP 服务器配置好、开箱即用。
|
||||
|
||||
也可以从 [ModelScope](https://modelscope.cn/mcp)、[mcp.so](https://mcp.so)、[composio.dev](https://composio.dev/toolkits) 等渠道获取，再按下文手动添加。
|
||||
</Info>
|
||||
|
||||
## 打开模型的函数调用功能
|
||||
## 三种运行模式
|
||||
|
||||
如图，将模型的`函数调用`功能打开。
|
||||
| 模式 | 适合场景 | 备注 |
|
||||
|------|----------|------|
|
||||
| Streamable HTTP (`mode: "http"`) | 远程 MCP 服务，支持 Streamable HTTP 传输 | LangBot 直接连接远程 URL |
|
||||
| SSE | 远程 MCP 服务，支持 SSE 传输 | LangBot 直接连接远程 URL |
|
||||
| stdio | 本地命令启动的 MCP Server | 仅在 Box Runtime 可用时支持 |
|
||||
|
||||
<img
|
||||
width="400px"
|
||||
src="/images/zh/deploy/mcp/mcp_01.png"
|
||||
alt="enable function call"
|
||||
/>
|
||||
<Note>
|
||||
MCP 工具需要流水线使用**内置 Agent**，并选择**已开启工具使用能力**的模型——见[模型](../models/readme)。Dify、n8n、Langflow、Coze 等外部 Runner 使用各自平台的工具机制。
|
||||
</Note>
|
||||
|
||||
## 创建MCP服务器
|
||||
## 安装 MCP 服务器
|
||||
|
||||
点击`插件管理` -\> `MCP管理`，如图所示：
|
||||
### 从 LangBot Space（首选）
|
||||
|
||||
<img
|
||||
width="1000px"
|
||||
src="/images/zh/deploy/mcp/mcp02.png"
|
||||
alt="server page"
|
||||
/>
|
||||
[LangBot Space](https://space.langbot.app) 是 LangBot 的官方市场，已上架多种 MCP 服务器。在 WebUI 的 `插件管理` → `MCP 管理` 页面浏览并一键安装，URL、命令、运行模式等参数由市场提供，无需手动填写。
|
||||
|
||||
点击右上角的`添加`，选择`添加 MCP 服务器`，
|
||||
适合大多数场景；接入未上架的服务再走下面的方式。
|
||||
|
||||
<img
|
||||
width="400px"
|
||||
src="/images/zh/deploy/mcp/mcp03.png"
|
||||
alt="create new mcp server"
|
||||
/>
|
||||
### 手动添加
|
||||
|
||||
比如使用 Fetch HTML 服务器，填写对应的 URL，点击`测试`用来测试 MCP 服务器，点`提交`添加此服务器。
|
||||
进入 `插件管理` → `MCP 管理`：
|
||||
|
||||
添加完成之后，点击卡片上的开关以连接 MCP 服务器，点击卡片可以看到 MCP 服务器的详情：
|
||||
<img width="1000px" src="/images/zh/deploy/mcp/mcp02.png" alt="MCP 管理页面" />
|
||||
|
||||
<img
|
||||
width="400px"
|
||||
src="/images/zh/deploy/mcp/mcp05.png"
|
||||
alt="detailed server"
|
||||
/>
|
||||
点击右上角 `添加` → `添加 MCP 服务器`，填写 URL（HTTP/SSE）或命令（stdio），点 `测试` 验证连通，点 `提交` 保存：
|
||||
|
||||
## 效果
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp03.png" alt="新建 MCP 服务器" />
|
||||
|
||||
需要在流水线设置中选用 `内置 Agent` 作为运行器，并使用支持函数调用的模型。
|
||||
保存后点击卡片上的开关连接 MCP，点击卡片可查看详情：
|
||||
|
||||
<img
|
||||
width="1000px"
|
||||
src="/images/zh/deploy/mcp/mcp04.png"
|
||||
alt="dialog with mcp"
|
||||
/>
|
||||
<img width="400px" src="/images/zh/deploy/mcp/mcp05.png" alt="MCP 服务器详情" />
|
||||
|
||||
## 在流水线启用
|
||||
|
||||
MCP 服务器添加后，还要在流水线扩展配置里决定 Agent 能看到哪些：
|
||||
|
||||
- 开启"启用所有 MCP Server"，或
|
||||
- 只绑定指定 MCP Server
|
||||
|
||||
未绑定的 MCP 工具不会进入该流水线的工具列表。
|
||||
|
||||
## stdio MCP 高级配置
|
||||
|
||||
stdio MCP 由 Box Runtime 托管，连接前 LangBot 会：
|
||||
|
||||
1. 创建或复用共享的 MCP Box session
|
||||
2. 如果能从命令推断本地项目路径，把项目 staging 到工作区
|
||||
3. 项目含 `requirements.txt` / `pyproject.toml` / `setup.py` / `setup.cfg` 时先安装依赖
|
||||
4. 通过 WebSocket relay 接 MCP 进程的 stdin/stdout
|
||||
|
||||
需要细化挂载、网络、超时等行为时，可在 MCP 配置的 `extra_args` 里加 `box` 覆盖项：
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "stdio",
|
||||
"extra_args": {
|
||||
"command": "python",
|
||||
"args": ["server.py"],
|
||||
"env": {},
|
||||
"box": {
|
||||
"host_path": "/path/to/mcp-project",
|
||||
"network": "on",
|
||||
"host_path_mode": "ro",
|
||||
"startup_timeout_sec": 120,
|
||||
"image": "python:3.11-slim"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
常用字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `host_path` | MCP 项目在宿主机上的目录。需在 `box.local.allowed_mount_roots` 允许范围内 |
|
||||
| `network` | 是否允许网络（依赖安装常用） |
|
||||
| `host_path_mode` | 准备 `host_path` 时的访问模式，默认 `ro`；stdio MCP 通常会先 staging 到工作区 |
|
||||
| `startup_timeout_sec` | Box 准备和依赖安装超时，默认 120 秒；连接等待会额外预留约 30 秒 |
|
||||
| `image` | Docker 后端使用的运行镜像 |
|
||||
|
||||
<Warning>
|
||||
stdio MCP 在 Box 中运行，依赖安装和进程启动受 sandbox profile、网络权限、资源限制和挂载白名单影响。
|
||||
</Warning>
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 检查项 |
|
||||
|------|--------|
|
||||
| MCP 连接失败 | URL、命令、参数、环境变量是否正确 |
|
||||
| stdio MCP 一直连接中 | Box Runtime 是否可用，`startup_timeout_sec` 是否过短 |
|
||||
| 依赖安装失败 | sandbox 是否允许网络，依赖文件是否正确 |
|
||||
| 本地文件无法访问 | `host_path` 是否存在，是否在 `allowed_mount_roots` 内 |
|
||||
| Agent 看不到 MCP 工具 | 流水线是否使用内置 Agent、模型是否启用工具使用能力、MCP 是否在流水线中绑定 |
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "配置模型 (Models)"
|
||||
title: "模型 (Models)"
|
||||
---
|
||||
|
||||
## LangBot Models
|
||||
@@ -45,8 +45,14 @@ LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Sp
|
||||
|
||||
模型能力方面，请根据具体模型特性来选择：
|
||||
|
||||
- 视觉能力：需要启用才可以识图
|
||||
- 函数调用：需要启用才可以在对话中使用 Agent 工具
|
||||
- **视觉能力**：启用后才能识别图片
|
||||
- **工具使用能力**（function calling / tool use）：启用后 LLM 才能在对话中调用工具
|
||||
|
||||
<Note>
|
||||
**只要想使用来自 MCP 服务器、沙箱内置工具（`exec`/`read`/`write`/`edit`/`glob`/`grep`）、Skills 的能力，都必须为模型启用工具使用能力。** 否则即使流水线绑定了这些扩展，Agent 也不会调用任何工具。
|
||||
|
||||
模型本身需要支持 function calling 才能勾选。不确定时请查阅模型供应商的文档。
|
||||
</Note>
|
||||
|
||||
### 嵌入模型 (Embedding Model)
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "修改对话流水线配置 (Pipelines)"
|
||||
title: "对话流水线 (Pipelines)"
|
||||
---
|
||||
|
||||
流水线控制了收到消息之后的处理流程，以及与大模型之间的信息交互。每个机器人可以绑定到一条流水线上，同一条流水线能被多个机器人绑定。
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "沙箱配置"
|
||||
---
|
||||
|
||||
沙箱由 LangBot 主进程配置，Box Runtime 负责实际执行。常规部署只需要选择后端、设置工作目录和安全预设。
|
||||
|
||||
<Note>
|
||||
本页所有 `box.*` 配置都写在 `data/config.yaml` 中。配置文件的位置和加载机制详见[系统环境设置](../../deploy/settings)。
|
||||
</Note>
|
||||
|
||||
## 推荐配置
|
||||
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local' # 自动从 Docker / Nsjail 里选可用的
|
||||
local:
|
||||
profile: 'default'
|
||||
host_root: './data/box'
|
||||
skills_root: 'skills'
|
||||
```
|
||||
|
||||
- `enabled`：沙箱总开关。设为 `false` 时，沙箱内置工具、Skill 添加/编辑、stdio MCP 托管等依赖 Box 的能力都不可用。
|
||||
- `backend`：见下文「后端选择」。
|
||||
- `local.profile`：安全预设，控制网络、挂载和资源限制。
|
||||
- `local.host_root`：主机上的沙箱工作目录，会映射为沙箱内的 `/workspace`。
|
||||
- `local.skills_root`：Skill 包目录；相对路径解析到 `host_root` 下，默认 `host_root/skills`。
|
||||
|
||||
<Note>
|
||||
Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端不可用时 Skill 列表为空，新增 / 编辑 / `register_skill` 都不可用；不会回退扫描 `data/skills/`。
|
||||
</Note>
|
||||
|
||||
## 后端选择
|
||||
|
||||
沙箱可以跑在**本机容器**或**云端**。`box.backend` 选择走哪一种：
|
||||
|
||||
| `backend` | 跑在哪 | 行为 |
|
||||
|-----------|--------|------|
|
||||
| `local`（默认） | 本机容器 | 自动从 Docker / Nsjail 里选可用的（Docker 优先） |
|
||||
| `docker` | 本机容器 | 强制使用 Docker，需要 Docker daemon |
|
||||
| `nsjail` | 本机容器 | 强制使用 Nsjail（仅 Linux），不支持自定义镜像 |
|
||||
| `e2b` | 云端 | 使用 [E2B](https://e2b.dev) 云沙箱，需要 API Key |
|
||||
|
||||
`local` 是「自动选择」的简写，不是和 `docker`/`nsjail` 平级的第四种后端。本机容器后端（`local`/`docker`/`nsjail`）**共用** `box.local.*` 配置段；云端后端用 `box.e2b.*` 配置段。
|
||||
|
||||
<Note>
|
||||
`backend` 是强制值。设为 `docker` 时如果 Docker 不可用，**不会**自动回退到 Nsjail 或 E2B——只有 `local` 会自动 fan-out。
|
||||
|
||||
也可以用环境变量 `BOX__BACKEND` 覆盖配置（优先级高于 `config.yaml`）。
|
||||
</Note>
|
||||
|
||||
## 安全预设
|
||||
|
||||
`box.local.profile` 控制本机后端的网络、挂载、资源限制：
|
||||
|
||||
| Profile | 网络 | 挂载 | 资源 | 建议场景 |
|
||||
|---------|------|------|------|----------|
|
||||
| `default` | 关闭 | 读写 | 默认限制 | 默认选择 |
|
||||
| `offline_readonly` | 关闭 | 只读 | 更严格 | 读取不可信文件 |
|
||||
| `network_basic` | 开启基础网络 | 读写 | 默认限制 | 需要访问 API 或下载依赖 |
|
||||
| `network_extended` | 开启完整网络 | 读写 | 更宽松 | 开发、调试、复杂任务 |
|
||||
|
||||
优先使用最小权限：不需要网络就用 `default` 或 `offline_readonly`；只把必要目录加入 `allowed_mount_roots`。
|
||||
|
||||
## 本机后端配置（box.local.*）
|
||||
|
||||
本机后端（`local` / `docker` / `nsjail`）共用以下配置：
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `local.profile` | `default` | 见上文「安全预设」 |
|
||||
| `local.image` | 空 | Docker 后端的自定义镜像；空 = 用 profile 默认 |
|
||||
| `local.host_root` | `./data/box` | 主机工作目录基础路径，映射为沙箱内 `/workspace` |
|
||||
| `local.default_workspace` | 空 | 默认工作空间名；空 = `<host_root>/default` |
|
||||
| `local.skills_root` | `skills` | Skill 包目录；相对路径解析到 `host_root` 下 |
|
||||
| `local.allowed_mount_roots` | `[host_root]` | Agent 可请求挂载的主机目录白名单 |
|
||||
| `local.workspace_quota_mb` | `null` | 工作区磁盘配额（MB），`null` = 用 profile 默认 |
|
||||
|
||||
## 云端后端配置（box.e2b.*）
|
||||
|
||||
设为 `backend: 'e2b'` 后配置：
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `e2b.api_key` | 空 | E2B API Key，也可用 `E2B_API_KEY` 环境变量 |
|
||||
| `e2b.api_url` | 空 | 自建 E2B 服务地址，也可用 `E2B_API_URL` |
|
||||
| `e2b.template` | 空 | 默认 E2B 模板 ID |
|
||||
|
||||
E2B 不需要本机 Docker 或 Nsjail，每次执行都走远程沙箱。
|
||||
|
||||
## Docker Compose 部署
|
||||
|
||||
Docker Compose 部署时，沙箱配置写在 `langbot` 服务上。LangBot 启动后会通过 INIT RPC 把配置下发给 `langbot_box`。
|
||||
|
||||
```yaml
|
||||
services:
|
||||
langbot_box:
|
||||
image: rockchin/langbot:latest
|
||||
container_name: langbot_box
|
||||
profiles: ["box", "all"]
|
||||
volumes:
|
||||
- ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]
|
||||
|
||||
langbot:
|
||||
image: rockchin/langbot:latest
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
- BOX__LOCAL__SKILLS_ROOT=skills
|
||||
- BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`langbot_box` 需要访问 Docker daemon。只在受信任环境中挂载 `docker.sock`；并保持 Box 根目录在主机和 `langbot_box` 容器内路径一致。
|
||||
</Warning>
|
||||
|
||||
如需 LangBot 连接外部 Box Runtime（例如远程主机），用 `box.runtime.endpoint` 指定 URL：
|
||||
|
||||
```yaml
|
||||
box:
|
||||
runtime:
|
||||
endpoint: 'ws://192.168.1.10:5410'
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 环境变量 | 写入配置 |
|
||||
|----------|----------|
|
||||
| `BOX__ENABLED` | `box.enabled` |
|
||||
| `BOX__BACKEND` | `box.backend` |
|
||||
| `BOX__LOCAL__PROFILE` | `box.local.profile` |
|
||||
| `BOX__LOCAL__IMAGE` | `box.local.image` |
|
||||
| `BOX__LOCAL__HOST_ROOT` | `box.local.host_root` |
|
||||
| `BOX__LOCAL__DEFAULT_WORKSPACE` | `box.local.default_workspace` |
|
||||
| `BOX__LOCAL__SKILLS_ROOT` | `box.local.skills_root` |
|
||||
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`，逗号分隔 |
|
||||
| `BOX__LOCAL__WORKSPACE_QUOTA_MB` | `box.local.workspace_quota_mb` |
|
||||
| `BOX__E2B__API_KEY` | `box.e2b.api_key` |
|
||||
| `BOX__E2B__API_URL` | `box.e2b.api_url` |
|
||||
| `BOX__E2B__TEMPLATE` | `box.e2b.template` |
|
||||
|
||||
<Note>
|
||||
不要在 `langbot_box` 服务上设置 `BOX__*` 或 `LANGBOT_BOX_*` 变量；这些变量不会被 Box Runtime 直接读取——它的配置由 LangBot 通过 INIT RPC 下发。
|
||||
</Note>
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: "沙箱 (Sandbox)"
|
||||
---
|
||||
|
||||
沙箱给内置 Agent 一个隔离的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。
|
||||
|
||||
启用沙箱后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。
|
||||
|
||||
## 内置工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `exec` | 在沙箱内执行 Shell 命令 |
|
||||
| `read` | 读取工作区文件 |
|
||||
| `write` | 创建或覆盖文件 |
|
||||
| `edit` | 字符串替换式修改文件 |
|
||||
| `glob` | 按 glob 模式查找文件 |
|
||||
| `grep` | 按正则搜索文件内容 |
|
||||
|
||||
`exec` 在沙箱容器内运行；其余五个直接读写主机映射到 `/workspace` 的目录。
|
||||
|
||||
<Note>
|
||||
这些工具面向内置 Agent。使用 Dify、n8n、Langflow、Coze 等外部 Runner 时，请使用对应平台自己的工具机制。
|
||||
</Note>
|
||||
|
||||
## 沙箱作用域
|
||||
|
||||
在流水线 AI 配置中可选择沙箱在不同消息间如何共享。默认"每个会话"足够大多数场景使用。
|
||||
|
||||
| 作用域 | 模板 | 共享范围 |
|
||||
|--------|------|---------|
|
||||
| 全局 | `{global}` | 所有用户共用一个沙箱 |
|
||||
| 每个会话（默认） | `{launcher_type}_{launcher_id}` | 同一群/私聊共用 |
|
||||
| 每个用户 | `{launcher_type}_{launcher_id}_{sender_id}` | 群里每位成员独立 |
|
||||
| 每个对话 | `{launcher_type}_{launcher_id}_{conversation_id}` | 按对话隔离 |
|
||||
| 每条消息 | `{query_id}` | 完全无状态 |
|
||||
|
||||
<Warning>
|
||||
同一作用域内的命令共享文件系统状态。需要完全隔离请选"每条消息"。
|
||||
</Warning>
|
||||
|
||||
## 生命周期
|
||||
|
||||
| 情况 | 行为 |
|
||||
|------|------|
|
||||
| 空闲超过 5 分钟 | 自动清理 |
|
||||
| 有 Box 托管进程（如 stdio MCP）在跑 | 不清理，进程结束后才释放 |
|
||||
| 配置 `persistent: true` | 永不自动清理 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. **准备后端**：本机装好 Docker，或选择 Nsjail / E2B
|
||||
2. **写入 `config.yaml`**：
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: 'local'
|
||||
local:
|
||||
host_root: './data/box'
|
||||
```
|
||||
3. **启动 LangBot**：沙箱自动启用
|
||||
4. **在流水线里**选择内置 Agent + 支持函数调用的模型
|
||||
|
||||
之后 Agent 会自动获得六个工具。详细配置见[沙箱配置](./config)。
|
||||
|
||||
## 关闭沙箱
|
||||
|
||||
设置 `box.enabled: false`。所有依赖沙箱的能力（内置工具、Skill 创建/编辑/激活、stdio MCP）会一并停用；http/sse 模式的 MCP 不受影响。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [沙箱配置](./config) — 后端、安全预设、挂载、环境变量
|
||||
- [运行时与扩展关系](./runtime-relationships) — 沙箱、Skills、MCP、插件如何分工
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "运行时与扩展关系"
|
||||
---
|
||||
|
||||
LangBot 里同时存在**插件、MCP、Skills、沙箱**四种扩展机制，容易混淆。本页帮你区分它们的职责和适用场景。
|
||||
|
||||
## 一句话区分
|
||||
|
||||
- **沙箱**：执行环境，让 Agent 跑命令、读写文件
|
||||
- **Skills**：按需激活的指令包，给 Agent 临时增加一段专业工作流
|
||||
- **MCP Server**：接入外部工具服务
|
||||
- **插件**：长期运行的扩展进程，可带配置页、事件监听、知识库
|
||||
|
||||
## 对照表
|
||||
|
||||
| 能力 | 提供方 | 给 Agent 的形式 | 何时使用 |
|
||||
|------|--------|----------------|---------|
|
||||
| 沙箱 | Box Runtime | 直接挂上 `exec/read/write/edit/glob/grep` 六件套 | Agent 要执行代码、读写文件 |
|
||||
| Skills | Box Runtime skill store | Agent 调 `activate` 后，指令通过 Tool Result 注入 | 想给 Agent 加一段流程/模板/脚本，按需触发 |
|
||||
| MCP Server | LangBot MCP Loader（stdio 模式由 Box 托管） | 工具直接进入可用工具列表 | 接入已有的 MCP 服务 |
|
||||
| 插件 | Plugin Runtime | 由插件系统暴露能力 | 长期能力、需要配置页/事件监听/知识库组件 |
|
||||
|
||||
## 流水线绑定
|
||||
|
||||
Skills、MCP Server、插件都属于**流水线扩展**。在 WebUI 安装/创建后，还要在流水线扩展配置里决定启用范围：
|
||||
|
||||
- 启用全部扩展，或
|
||||
- 只绑定指定的扩展
|
||||
|
||||
Skills 的绑定决定 Agent **能看到哪些技能**（影响 `<available_skills>` 列表）。具体技能内容只有 Agent 调用 `activate` 后才会注入。
|
||||
|
||||
## 排障入口
|
||||
|
||||
| 现象 | 优先检查 |
|
||||
|------|---------|
|
||||
| Agent 没有 `exec/read/write` 工具 | `box.enabled`、后端是否可用、流水线是否用内置 Agent |
|
||||
| Skill 列表为空 | Box Runtime 状态、`box.local.skills_root`、流水线绑定 |
|
||||
| stdio MCP 启动失败 | Box Runtime 状态、MCP 命令和环境变量、启动超时 |
|
||||
| Docker 部署沙箱启不来 | `langbot_box` 是否挂载 `docker.sock`、Box 根目录路径是否一致 |
|
||||
| 文件读写失败 | `box.local.host_root`、`box.local.allowed_mount_roots` |
|
||||
| 后端选择不生效 | 确认 `BOX__BACKEND` 设在 `langbot` 服务上，不是 `langbot_box` |
|
||||
|
||||
<Note>
|
||||
沙箱内置工具和 Skills 当前面向内置 Agent。外部 Runner（Dify、n8n、Langflow、Coze 等）应使用各自平台的工具和执行机制。
|
||||
</Note>
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: "技能 (Skills)"
|
||||
---
|
||||
|
||||
Skill 是一个**按需激活**的指令包：用户描述匹配时，Agent 调用 `activate` 工具把这个技能的指令拉进上下文，然后按指令完成任务。未激活的技能不占用上下文。
|
||||
|
||||
适合给 Agent 加一段**专业流程、模板或脚本**——比如"分析 Python 项目"、"PDF 表单填充"、"代码评审"——而不必每个对话都把指令塞进 System Prompt。
|
||||
|
||||
## 与插件、MCP 的区别
|
||||
|
||||
| 你想做的事 | 用这个 |
|
||||
|------------|--------|
|
||||
| 按需触发的一段工作流（可带脚本、模板） | Skill |
|
||||
| 接入已有的 MCP 工具服务 | MCP Server |
|
||||
| 长期能力，需要配置页、事件、知识库 | 插件 |
|
||||
|
||||
详见[运行时与扩展关系](../sandbox/runtime-relationships)。
|
||||
|
||||
## 安装技能
|
||||
|
||||
<Note>
|
||||
技能依赖沙箱：`box.enabled` 为 `true` 且 Docker / Nsjail / E2B 至少一个可用时，才能安装、激活和编辑技能。详见[沙箱配置](../sandbox/config)。
|
||||
</Note>
|
||||
|
||||
### 从 LangBot Space（首选）
|
||||
|
||||
[LangBot Space](https://space.langbot.app) 是 LangBot 的官方市场，已上架多种技能。在 WebUI 的 Skills 页面浏览并一键安装，无需自己编写 `SKILL.md` 或准备资源文件。
|
||||
|
||||
适合大多数场景。需要自定义流程再走下面的方式。
|
||||
|
||||
### 自己创建技能
|
||||
|
||||
**WebUI** — Skills 页面新建、上传 zip 包、从 GitHub 导入。
|
||||
|
||||
**沙箱 + `register_skill`**：
|
||||
1. 在沙箱 `/workspace` 下准备好目录和 `SKILL.md`
|
||||
2. 让 Agent 调用 `register_skill(path="/workspace/my-skill")`
|
||||
|
||||
两种方式都会写入 Box Runtime 管理的 skill store。
|
||||
|
||||
## 在流水线启用
|
||||
|
||||
技能装好之后，还要在流水线扩展配置里决定 Agent 能看到哪些：
|
||||
|
||||
- 开启"启用所有技能"，或
|
||||
- 只绑定指定技能
|
||||
|
||||
绑定只影响 `<available_skills>` 列表（即 Agent 能从哪些技能里挑），完整指令永远等 `activate` 被调用后才注入。
|
||||
|
||||
## 编写 SKILL.md
|
||||
|
||||
技能就是一个目录加一个 `SKILL.md`。frontmatter 写元数据，正文是 Agent 激活后会收到的指令：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
display_name: 代码评审助手
|
||||
description: 审查代码并给出改进建议；用户提到 review、评审、代码改进时触发
|
||||
---
|
||||
|
||||
## 执行步骤
|
||||
|
||||
1. 用 `read` 浏览相关文件
|
||||
2. 检查可读性、潜在 bug、安全问题
|
||||
3. 给出按优先级排序的改进建议
|
||||
```
|
||||
|
||||
LangBot 当前读取以下三个字段：
|
||||
|
||||
| 字段 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | 创建/注册时 | 唯一标识，1–64 字符 |
|
||||
| `description` | 强烈建议 | Agent 用它判断何时激活——越具体越能选中 |
|
||||
| `display_name` | 否 | UI 显示名 |
|
||||
|
||||
`description` 是 Agent 挑技能的唯一依据，要写清楚**功能、适用场景、可能的触发关键词**。
|
||||
|
||||
完整规范见 [agentskills.io](https://agentskills.io/home)。其它字段（`license`、`metadata` 等）可保留供未来兼容，当前不会被读取。
|
||||
|
||||
**带资源的技能**在 `SKILL.md` 同级放 `scripts/`、`templates/` 等目录，激活后 Agent 通过 `/workspace/.skills/{skill-name}/` 访问。
|
||||
|
||||
### Agent 可用的工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `activate` | Agent 判断匹配时自动调用，把 SKILL.md 拉进上下文 |
|
||||
| `register_skill` | 把沙箱里准备好的目录注册为新技能 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 检查项 |
|
||||
|------|--------|
|
||||
| 技能列表为空 | `box.enabled`、Box Runtime 状态、`box.local.skills_root` |
|
||||
| Agent 不激活技能 | `description` 是否具体、流水线是否绑定、模型是否支持函数调用 |
|
||||
| 激活后找不到文件 | 文件需在 Skill 包内，路径是 `/workspace/.skills/{skill-name}/` |
|
||||
| `register_skill` 报错 | 路径必须在 `/workspace` 下，目录或两层内子目录需含 `SKILL.md` |
|
||||
|
||||
<Note>
|
||||
Skills 当前面向内置 Agent，依赖函数调用和沙箱后端。外部 Runner（Dify、n8n、Langflow、Coze 等）请使用各自平台的等价机制。
|
||||
</Note>
|
||||
Reference in New Issue
Block a user