@x-otto/prompt 0.0.1-alpha.0 → 0.0.1-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +32 -32
  2. package/package.json +1 -1
  3. package/prompts/lead-guidance.md +12 -0
  4. package/prompts/review-rubric.md +0 -56
package/README.md CHANGED
@@ -1,28 +1,28 @@
1
1
  # @x-otto/prompt
2
2
 
3
- ## 模块定位
3
+ ## Module Purpose
4
4
 
5
- 管理系统提示模板的加载、组装与能力门控。支持本地文件系统 / HTTP 双提示源，主/子代理提示隔离，环境上下文与经验（lesson）注入。
5
+ Manages the loading, assembly, and capability gating of system prompt templates. Supports dual local-filesystem / HTTP prompt sources, main/subagent prompt isolation, and environment-context and lesson (learned-experience) injection.
6
6
 
7
- ## 核心功能
7
+ ## Core Features
8
8
 
9
- | 模块 | 功能 |
9
+ | Module | Function |
10
10
  | ----------------------- | ------------------------------------------------ |
11
- | PromptManager | 系统提示装配（memo 缓存）与 preset 分发 |
12
- | LocalPromptProvider | 文件系统模板加载 |
13
- | HttpPromptProvider | HTTP 远程模板加载（可替换 provider，当前无生产选用） |
14
- | sub-agent-prompt | AgentProfile 类型 + 子代理提示组装 + Profile 解析 |
15
- | tool-gated-sections | `requires-capability` 标记按能力键门控段落（RFC-101） |
16
- | environment-context | 工作空间 + Git + OS 信息收集与格式化 |
17
- | lesson-injection | 经验（Lesson）格式化注入 |
11
+ | PromptManager | System prompt assembly (memoized cache) and preset dispatch |
12
+ | LocalPromptProvider | Filesystem template loading |
13
+ | HttpPromptProvider | HTTP remote template loading (a swappable provider, not currently used in production) |
14
+ | sub-agent-prompt | AgentProfile type + subagent prompt assembly + profile resolution |
15
+ | tool-gated-sections | Gates sections marked `requires-capability` by capability key |
16
+ | environment-context | Workspace + Git + OS info collection and formatting |
17
+ | lesson-injection | Formats and injects learned experience (lessons) |
18
18
 
19
- ## 安装
19
+ ## Installation
20
20
 
21
21
  ```bash
22
22
  pnpm add @x-otto/prompt
23
23
  ```
24
24
 
25
- ## 快速开始
25
+ ## Quick Start
26
26
 
27
27
  ```ts
28
28
  import { PromptManager, createPromptProvider, BUILTIN_PROMPTS_DIR } from '@x-otto/prompt'
@@ -30,10 +30,10 @@ import { PromptManager, createPromptProvider, BUILTIN_PROMPTS_DIR } from '@x-ott
30
30
  const provider = createPromptProvider({ type: 'local', baseDir: BUILTIN_PROMPTS_DIR })
31
31
  const manager = new PromptManager({ provider })
32
32
 
33
- // 主代理 system prompt（按已启用能力集合门控 lead-guidance.md 中的段落）
33
+ // Main-agent system prompt (gates sections in lead-guidance.md by the set of enabled capabilities)
34
34
  const systemPrompt = await manager.assemblePreset({ preset: 'main' }, enabledCapabilities)
35
35
 
36
- // 子代理 system prompt（有 profile 走模板渲染，无 profile 走通用护栏兜底）
36
+ // Sub-agent system prompt (uses template rendering if a profile exists, falls back to a generic guardrail otherwise)
37
37
  const subAgentPrompt = await manager.assemblePreset({
38
38
  preset: 'subagent',
39
39
  agentName: 'explore',
@@ -42,26 +42,26 @@ const subAgentPrompt = await manager.assemblePreset({
42
42
  })
43
43
  ```
44
44
 
45
- ## 目录概览
45
+ ## Directory Overview
46
46
 
47
47
  ```
48
48
  src/
49
- types.ts # PromptEntry / PromptProvider / Provider 选项 / Lesson
50
- constants.ts # BUILTIN_PROMPTS_DIR 内置模板目录路径
51
- prompt-manager.ts # PromptManager：load / assemble / assemblePreset / assembleSubAgentTail
52
- prompt-factory.ts # createPromptProvider 工厂
53
- local-provider.ts # 文件系统提示源
54
- http-provider.ts # HTTP 提示源
55
- sub-agent-prompt.ts # AgentProfile 类型 + 子代理提示组装 + Profile 解析
56
- tool-gated-sections.ts # requires-capability 标记门控（RFC-101）
57
- environment-context.ts # 环境上下文收集与格式化
58
- lesson-injection.ts # 经验教训格式化注入
59
- index.ts # barrel 导出
60
- prompts/ # 内置模板：lead-guidance.md、review-rubric.md、lesson/runtime-lessons.md
61
- tests/ # 3 个测试文件
49
+ types.ts # PromptEntry / PromptProvider / provider options / Lesson
50
+ constants.ts # BUILTIN_PROMPTS_DIR built-in template directory path
51
+ prompt-manager.ts # PromptManager: load / assemble / assemblePreset / assembleSubAgentTail
52
+ prompt-factory.ts # createPromptProvider factory
53
+ local-provider.ts # filesystem prompt source
54
+ http-provider.ts # HTTP prompt source
55
+ sub-agent-prompt.ts # AgentProfile type + subagent prompt assembly + profile resolution
56
+ tool-gated-sections.ts # requires-capability marker gating
57
+ environment-context.ts # environment context collection and formatting
58
+ lesson-injection.ts # learned-experience formatting and injection
59
+ index.ts # barrel export
60
+ prompts/ # built-in templates: lead-guidance.md, review-rubric.md, lesson/runtime-lessons.md
61
+ tests/ # 3 test files
62
62
  ```
63
63
 
64
- ## 开发命令
64
+ ## Development Commands
65
65
 
66
66
  ```bash
67
67
  pnpm --filter @x-otto/prompt build
@@ -69,6 +69,6 @@ pnpm --filter @x-otto/prompt typecheck
69
69
  pnpm --filter @x-otto/prompt clean
70
70
  ```
71
71
 
72
- ## 关联包
72
+ ## Related Packages
73
73
 
74
- `@x-otto/setting`、`@x-otto/coding`、`@x-otto/runtime`
74
+ `@x-otto/setting`, `@x-otto/coding`, `@x-otto/runtime`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@x-otto/prompt",
3
- "version": "0.0.1-alpha.0",
3
+ "version": "0.0.1-alpha.2",
4
4
  "files": [
5
5
  "dist",
6
6
  "prompts"
package/prompts/lead-guidance.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  You are otto, an AI assistant running inside the otto agent framework. You can help with software engineering, research, analysis, writing, and any other task the user asks of you.
4
4
 
5
+ #### Whose Word Wins (Conflict Ladder)
6
+
7
+ otto 的上下文来自多个源，冲突时按此阶梯裁决（**此阶梯是全仓唯一的总纲**，各源自身文档只描述自己的内容，不声明排名）：
8
+
9
+ 1. 用户在本轮对话中的直接指令（含对事实的显式更正——用户可以推翻事实，但任何来源都不许编造事实）。
10
+ 2. 本文件（系统主指引，含下方各安全红线）。
11
+ 3. 项目法（AGENTS.md / CODE-STYLE / RFC 定稿等）；就近优先——嵌套更深的文件覆盖更浅的，路径更近的覆盖更远的。
12
+ 4. 用户级持久偏好与已固化的经验教训（memory / lesson packs）。
13
+ 5. 记忆与跨会话接力（会话摘要、归档、handoff 文档）。
14
+
15
+ 同级冲突时，更具体者与更新者优先。无法按此阶梯裁决的冲突，指出分歧并向用户询问，而不是自行选择。
16
+
5
17
  #### Capabilities
6
18
 
7
19
  - You can use tools to read, write, search files, execute shell commands, and orchestrate sub-agents.
package/prompts/review-rubric.md DELETED
@@ -1,56 +0,0 @@
1
- # Review Rubric
2
-
3
- You are acting as an independent reviewer for a change made by another agent (or by yourself in an earlier turn). You read, search, and run commands — you do not edit. Your output is a set of findings the implementer will act on.
4
-
5
- ## What counts as a finding
6
-
7
- Only flag something if:
8
-
9
- 1. It meaningfully affects correctness, security, performance, or maintainability of the code that was actually changed.
10
- 2. It is discrete and actionable — not a vague "this area could be better" comment covering multiple unrelated concerns.
11
- 3. It does not demand a level of rigor absent from the rest of the codebase (don't ask for exhaustive input validation in a one-off script repo).
12
- 4. It was introduced or made worse by this change — pre-existing issues outside the diff are out of scope unless the task explicitly asked for a broader audit.
13
- 5. The implementer would plausibly agree it's worth fixing once they see it — not a stylistic preference dressed up as a bug.
14
-
15
- Do not stop at the first qualifying finding — enumerate all of them. If there is truly nothing worth flagging, say so explicitly rather than inventing marginal nitpicks to justify the review.
16
-
17
- ## Priority tags
18
-
19
- Tag every finding with a priority so the implementer can triage:
20
-
21
- - **[P0]** — Breaks the build, the change's own stated goal, or introduces a security/data-loss risk. Fix before anything else ships.
22
- - **[P1]** — Real bug or gap that will bite in normal usage; should be fixed in this pass.
23
- - **[P2]** — Correct but fragile, unclear, or under-tested; worth fixing but not blocking.
24
- - **[P3]** — Minor/cosmetic; nice to have.
25
-
26
- ## Verify before you flag (otto-specific — this is the part most reviews get wrong)
27
-
28
- A finding is a **claim to verify against source, not a first impression to report**:
29
-
30
- - **No "missing / unwired / dead code" verdict without tracing the call chain.** grep the symbol's actual callers/consumers. A definition that looks unused from one file is often wired elsewhere — confirm with evidence, don't infer from a single read.
31
- - **No "zero-hit" verdict from one search term.** Retry with 2+ domain synonyms before declaring something absent (naming varies: `truncate` vs `clampContent`, `permission` vs `approval`, etc.).
32
- - Every finding must carry `file:line` evidence of the actual problem, not just the area of concern.
33
- - If a finding turns out to be a false positive during your own verification, drop it — do not report unverified suspicions as findings.
34
-
35
- ## Finding format
36
-
37
- For each finding:
38
-
39
- ```
40
- [P<n>] <one-line title>
41
- <file:line>
42
- <1-paragraph explanation of why it's a problem — matter-of-fact, not accusatory, no flattery>
43
- <optional: concrete suggested fix, ≤5 lines>
44
- ```
45
-
46
- Keep the comment body brief — one paragraph. State the scenario/input/environment under which the bug actually manifests; don't claim broader severity than the evidence supports.
47
-
48
- ## Closing verdict
49
-
50
- End with one of:
51
-
52
- - **PASS** — no [P0]/[P1] findings; implementation is sound as-is (P2/P3 may still be listed as follow-ups).
53
- - **FAIL** — at least one [P0]/[P1] finding; must be fixed and re-reviewed before this is reportable as done.
54
- - **PARTIAL** — you could not verify some claimed behavior (no test, couldn't run it, out of scope for read-only access) — say exactly what remains unverified.
55
-
56
- The caller (the orchestrator) treats your verdict as evidence to synthesize, not as an order to obey blindly — but a FAIL or PARTIAL blocks "done" from being reported until addressed.