@yandy0725/pi-lark 0.1.0

package/skills/lark-drive/references/lark-drive-workflow-knowledge-organize-execution.md

@@ -0,0 +1,200 @@
+# 知识整理工作流：Execution
+
+Loaded by states: `EXECUTE`, `VERIFY`.
+
+This file owns confirmed write execution, PathTokenMap, progress reporting, verification, next suggestions, and execution-stage failure handling. It MUST NOT generate or revise plans.
+
+## Required Context
+
+Before executing rules in this file:
+
+1. `active_plan_items` and `execution_scope` MUST already exist from [`lark-drive-workflow-knowledge-organize-planning.md`](lark-drive-workflow-knowledge-organize-planning.md).
+2. `target_tree` and `resource_items` MUST already exist.
+3. Use the `PlanItem` structure already produced by the planning phase. Do not regenerate or revise plans in this file.
+4. Follow command syntax, scope requirements, and confirmation behavior from referenced shortcut docs.
+5. Follow `Non-goals` from the main workflow entry. Do not execute excluded operations from this file.
+6. Maintain internal `rollback_snapshot` and `execution_journal` during writes, but do not mention recovery on the normal successful path.
+
+## State: EXECUTE
+
+Entry: user explicitly confirmed execution scope.
+
+Allowed writes only:
+
+- 创建 Drive 文件夹：`drive +create-folder`
+- 移动 Drive 文件 / 文件夹：`drive +move`
+- 创建 Wiki 节点：`wiki +node-create`
+- 移动已有 Wiki 节点：`wiki +move --node-token`
+- 续跑异步移动任务：`drive +task_result`
+- 单个资源权限申请：`drive +apply-permission`
+
+MUST:
+
+1. Resolve all target paths through `PathTokenMap`.
+2. Build internal `rollback_snapshot` for all move items in confirmed scope before any write operation.
+3. Initialize `execution_journal` before any write operation.
+4. Create target folders / nodes shallow to deep.
+5. Save returned tokens immediately.
+6. Append an `execution_journal` entry after every create / move / async continuation.
+7. Apply parent-child source move ordering.
+8. Execute only confirmed scope.
+9. Record success/failure per `PlanItem`.
+10. Apply `Progress Reporting`.
+
+MUST NOT:
+
+- Execute operations listed in `Non-goals`.
+- Rename or patch resource titles.
+- Move using path string instead of token.
+- Use `wiki +move` docs-to-wiki mode.
+- Output rollback snapshot, rollback readiness, or execution journal on the normal successful path.
+
+### Internal Recovery Hooks
+
+These hooks are mandatory internal state maintenance. They do not create user-facing output on the normal path.
+
+Rules:
+
+1. Build `rollback_snapshot` before the first write command.
+2. Include only compact fields needed for recovery. Do not store full API responses.
+3. Append `execution_journal` immediately after each write attempt, including successful creates, successful moves, failed moves, and async continuation results.
+4. If snapshot or journal cannot be maintained, stop before further writes and report the blocker.
+5. If a write blocker occurs after one or more successful moves, report the blocker and ask whether the user wants to try restoring to `整理前的位置`.
+6. Do not load the rollback phase or execute recovery until the user explicitly chooses to try restore.
+
+Recovery question template:
+
+```text
+执行暂停：已成功移动 <moved_success_count> 项，失败 <failed_count> 项。
+
+执行出现错误，已有部分资源移动成功。是否需要尝试恢复到整理前的位置？
+```
+
+### Progress Reporting
+
+Small execution means `created_total + moved_total <= 50`.
+
+For small executions, a final execution result is enough. For larger or long-running executions (`created_total + moved_total > 50`), the agent MUST periodically report progress by elapsed time and meaningful stage boundaries rather than by operation count alone.
+
+Progress reports SHOULD be stage-specific. Include only fields relevant to the current stage. Do not output empty, unknown, or irrelevant fields.
+
+Required fields by stage:
+
+- Start: total create count, total move count, reporting cadence.
+- Create stage finished: created count, failed count.
+- Move stage progress / finished: current moved count as `<moved_done>/<moved_total>`, failed count, optional recent item.
+- Blocked: current stage, completed count, blocker, required next action.
+
+Examples:
+
+- `执行开始：本次将创建 <created_total> 个目录 / 节点，移动 <moved_total> 个资源。任务较大，我会约每 60 秒汇报一次进度。`
+- `执行进度：移动资源 <moved_done>/<moved_total>，失败 <failed_count>。`
+- `执行暂停：<current_stage> 阶段遇到 <blocker>，已完成 <done>/<total>，需要 <required_action>。`
+
+Rules:
+
+1. When `created_total + moved_total > 50`, output one progress notice when execution starts.
+2. After the create stage finishes, output one progress report when `created_total > 0`.
+3. During the move stage, output a progress report about every 60 seconds, and once more when the move stage finishes.
+4. Every move-stage progress report MUST include the current moved count as `<moved_done>/<moved_total>` and failed count, even if fewer than 50 additional moves completed since the previous report.
+5. If execution is blocked by auth, permission, unresolved token, or API error, output the current progress and blocker before stopping.
+6. Do not mention operation-count milestones such as "not yet reached 50 moves"; progress is time-based.
+7. Do not output filler messages such as "still running", "no failure yet", or "not yet reached the next progress point" without current counts.
+8. Do not report progress after every item unless the user explicitly asks for verbose execution logs.
+
+## PathTokenMap
+
+`PathTokenMap` maps target paths to real tokens before execution.
+
+| Scope | Mapping |
+|-------|---------|
+| Drive | `target_path -> folder_token` |
+| Wiki | `target_path -> node_token`, with `space_id` retained |
+
+Rules:
+
+1. Scan existing target folders / nodes before creating new ones.
+2. Create planned folders / nodes from shallow to deep.
+3. Save returned `folder_token` or `node_token` immediately after each successful create.
+4. Execute `move` only when `target_parent_path` resolves to a token.
+5. If same-name target ambiguity exists, inspect existing children when possible; otherwise mark `needs_review=true`.
+6. Before writing to `my_library` root, resolve the real `space_id` according to `lark-wiki`.
+
+## State: VERIFY
+
+Entry: execution finished.
+
+MUST:
+
+1. Rescan target scope.
+2. Compare each executed `PlanItem` with actual path/token.
+3. Verify items covered by `covered_by_parent_move=true`.
+4. Output success/failure/manual-confirmation counts.
+5. Report mismatches with expected vs actual path/token.
+6. Verify non-reused source containers planned for cleanup are no longer left in their original top-level position.
+7. Verify reused target containers remain in place.
+8. If serious mismatches exist, ask whether the user wants to try restoring to `整理前的位置`.
+9. Do not load the rollback phase or execute recovery until the user explicitly chooses to try restore.
+
+Verification table:
+
+| plan_id | 动作 | 标题 | 预期目标 | 实际目标 | 预期 token | 实际 token | 状态 | 失败原因 |
+|---------|------|------|----------|----------|------------|------------|------|----------|
+
+### Verification Result
+
+```text
+执行完成。
+
+| 项目 | 数量 |
+|------|------|
+| 创建成功 |  |
+| 移动成功 |  |
+| 待人工确认 |  |
+| 失败 |  |
+
+| plan_id | 动作 | 预期目标 | 实际目标 | 状态 | 失败原因 |
+|---------|------|----------|----------|------|----------|
+```
+
+Serious mismatch recovery question template:
+
+```text
+验证发现 <mismatch_count> 项结果与计划不一致。
+
+是否需要尝试恢复到整理前的位置？
+```
+
+### Next Suggestions
+
+Only output `建议下一步` when at least one trigger exists. Do not add generic suggestions when execution and verification are clean.
+
+Triggers:
+
+- `partial=true`: inventory or content read was incomplete.
+- Manual confirmation or low-confidence items remain.
+- Failed items exist.
+- One target folder / Wiki node contains more than 100 direct child resources after organization.
+- Root-level loose resources remain.
+- Non-reused source containers remain in their original top-level position after cleanup was planned.
+- Verification found mismatches.
+
+Template:
+
+```text
+建议下一步：
+- <trigger-based suggestion>
+```
+
+## Execution Failure Handling
+
+| Failure / Blocker | Agent MUST Do | Agent MUST NOT Do |
+|-------------------|---------------|-------------------|
+| Missing API scope | Follow `lark-shared` permission handling and stop | Do not retry the same command repeatedly |
+| Resource access denied | Stop and follow the main workflow `Permission Request Gate` | Do not request permission automatically or in batch |
+| Target path cannot resolve to token | Mark affected plan item failed or `needs_review=true` | Do not execute move with a path string |
+| Target path has same-name ambiguity | Read existing children if possible; otherwise mark `needs_review=true` | Do not create duplicate target blindly |
+| Async move returns `ready=false` or `next_command` | Follow the returned async continuation command | Do not assume completion |
+| Parent-child move conflict | Follow source-depth ordering; move divergent children before parent | Do not move parent first when child target differs |
+| Verification mismatch | Report expected vs actual path/token and failure reason | Do not silently mark success |
+| Write blocker after successful moves | Report current progress and ask whether to try restoring to `整理前的位置` | Do not load rollback phase or execute recovery without explicit user choice |

package/skills/lark-drive/references/lark-drive-workflow-knowledge-organize-planning.md

@@ -0,0 +1,336 @@
+# 知识整理工作流：Planning
+
+Loaded by states: `PLAN_GENERATION`, `EXEC_CONFIRM`.
+
+This file owns plan generation, plan revision, user-facing pagination, and execution confirmation. It MUST NOT perform write operations.
+
+## Required Context
+
+Before executing rules in this file:
+
+1. `resource_items`, `classification_rules`, and `target_tree` MUST already exist.
+2. Follow command syntax, scope requirements, and confirmation behavior from referenced shortcut docs.
+3. Follow `Non-goals` from the main workflow entry. Do not execute excluded operations from this file.
+
+## State: PLAN_GENERATION
+
+Entry: `target_tree` exists after the user confirmed the organization approach.
+
+MUST:
+
+1. Generate complete internal `plan_items`.
+2. Build `DisplayItem` only for user-facing pages.
+3. Apply `Plan Generation`.
+4. Apply `Plan Pagination`.
+5. Set `active_plan_items` to the latest complete plan.
+6. Keep complete plan internally even if only one page is displayed.
+7. Apply `Plan Generation Progress Reporting`.
+8. Output `Target Tree And Plan Overview` or requested plan page, then wait.
+
+### Plan Generation
+
+| Condition | Agent MUST Do |
+|-----------|---------------|
+| Target path appears in any plan item | Ensure the path exists in `target_tree` |
+| Source parent and descendants share same target subtree | Move parent only; mark descendants `covered_by_parent_move=true` |
+| A child target differs from parent target | Move divergent child before parent; order by `source_depth` from deep to shallow |
+| Target directory / node does not exist | Add `create_folder` / `create_node` before move |
+| Resource is root-level and target path differs from current path | Add a `move` plan item; do not leave root-level resources in place by default |
+| Resource has `needs_review=true` because classification evidence is insufficient | Set `target_path` to manual confirmation target, set `action=move`, and preserve `needs_review_reason` |
+| Top-level folder / Wiki node has descendants that share the same target subtree | Move the parent folder / node only; descendants are covered by parent move |
+| Top-level folder / Wiki node has descendants with divergent target subtrees | Move divergent descendants first; then move the parent only if it still has a target path or needs manual confirmation |
+| Source container is reused as a target container | Keep the container in place; do not move it as source-container cleanup |
+| Non-reused source container has descendants moved elsewhere | Add an explicit folder / node move plan item after descendant moves; target defaults to the source-container cleanup target |
+| Source container handling is ambiguous | Move it to the manual confirmation target or mark `needs_review=true`; do not leave it in the root by default |
+| Target parent token unresolved | Keep plan item but block execution until token is resolved |
+| Resource title is poor or inconsistent | Report the naming issue only; do not create rename or title-patch plan items |
+
+### Plan Generation Progress Reporting
+
+Plan generation can be long-running when `resource_items` is large or source-container parent / child move ordering is complex.
+
+Rules:
+
+1. If plan generation starts with more than 500 `resource_items`, output one concise start notice with the resource count and that no write operation is being executed.
+2. If plan generation runs longer than about 60 seconds, output progress about every 60 seconds.
+3. Progress reports SHOULD include only fields currently known: processed resource count, generated plan item count, create count, move count, source-container move count, review count, and current step.
+4. Do not display unpaginated plan details as progress. Complete `plan_items` remain internal until the normal paginated output.
+5. Do not ask the user to continue during plan generation unless auth, permission, API, target scope, or environment blockers occur.
+6. Do not output filler such as "still running" without current counts or current step.
+
+Example:
+
+```text
+计划生成进度：已处理 <processed_count>/<resource_count> 项资源，生成 <plan_item_count> 项计划，其中创建 <create_count> 项、移动 <move_count> 项。继续计算父子目录移动顺序，不会执行创建或移动。
+```
+
+## PlanItem
+
+`PlanItem` is for internal execution. It may contain tokens and internal enums.
+
+| Field | Meaning |
+|-------|---------|
+| `plan_id` | Stable unique ID for plan / verification, such as `P001` |
+| `source_path` | Current path |
+| `title` | Resource title |
+| `type` | Resource type |
+| `source_token` | Drive token or normal resource token |
+| `source_node_token` | Wiki node token; empty for non-Wiki resources |
+| `source_parent_token` | Current parent folder token or parent Wiki node token |
+| `source_depth` | Original depth in source tree |
+| `target_path` | Target path |
+| `target_parent_path` | Target parent path |
+| `target_parent_token` | Target parent token; may be empty during planning, MUST be resolved before execution |
+| `action` | Internal enum: `keep` / `create_folder` / `create_node` / `move` |
+| `covered_by_parent_move` | Whether an ancestor move already covers this item |
+| `reason` | Classification reason |
+| `evidence_paths` | Evidence paths |
+| `evidence_count` | Evidence count or hit count |
+| `confidence` | Internal enum: `high` / `medium` / `low` |
+| `needs_review` | Whether human review is required |
+| `needs_review_reason` | Reason requiring human review |
+| `rollback_origin_kind` | Internal recovery origin marker: `drive_folder` / `drive_root` / `wiki_node` / `wiki_space_root` / `unknown` |
+| `rollback_origin_token` | Original parent token when applicable; empty for root markers |
+| `rollback_origin_space_id` | Original Wiki space ID when `rollback_origin_kind=wiki_space_root` |
+| `rollback_supported` | Whether this move item can be restored automatically if recovery is requested |
+| `rollback_blocker` | Internal reason when `rollback_supported=false` |
+
+### Rollback Origin Readiness
+
+This is an internal execution-safety rule. Do not expose rollback readiness on the normal user-facing execution confirmation path.
+
+Rules:
+
+1. `action=move` items entering execution SHOULD have `rollback_origin_kind`.
+2. `rollback_origin_kind` can be:
+   - `drive_folder`: original Drive parent folder token is known.
+   - `drive_root`: original location is the Drive root.
+   - `wiki_node`: original Wiki parent node token is known.
+   - `wiki_space_root`: original location is the Wiki space root and `rollback_origin_space_id` is known.
+3. If `rollback_origin_kind` is missing or `unknown`, the agent MUST try to resolve it before execution from `ResourceItem.parent_token`, traversal context, `source_path`, `space_id`, or `wiki +node-get` for Wiki resources.
+4. If the origin is still unresolved, set `rollback_supported=false` and `rollback_blocker`, but do not block the entire execution solely because recovery is unsupported.
+5. Target resolution remains mandatory: a move item with unresolved `target_parent_token` MUST NOT execute.
+6. Internal recovery metadata MUST NOT change `DisplayItem` output on the normal successful path.
+
+## DisplayItem
+
+`DisplayItem` is for user-facing output. It MUST NOT expose raw internal enum values.
+
+| Display Field | Source |
+|---------------|--------|
+| `序号` | Page-local row number |
+| `当前位置` | `source_path` |
+| `标题` | `title` |
+| `类型` | Human-readable `type` when possible; raw type is acceptable only when there is no clearer label |
+| `目标位置` | `target_path` |
+| `动作` | Convert from `action` using action display map |
+| `原因` | `reason` |
+| `置信度` | Convert from `confidence` using confidence display map |
+| `待确认原因` | `needs_review_reason` |
+
+Action display map:
+
+| Internal Enum | User-Facing Label |
+|---------------|-------------------|
+| `keep` | 保持不变 |
+| `create_folder` | 创建文件夹 |
+| `create_node` | 创建知识库节点 |
+| `move` | 移动到目标目录 |
+
+`needs_review=true` is a review state, not an action. A review item MUST still use `action=move` when its target is the manual confirmation target.
+
+### Manual Confirmation Target
+
+Resources with insufficient classification evidence MUST be moved to the manual confirmation target after the user confirms execution.
+
+Rules:
+
+1. The target tree MUST include `待人工确认` or an equivalent user-specified manual confirmation path.
+2. For Drive scopes, the manual confirmation target is a Drive folder.
+3. For Wiki scopes, the manual confirmation target is a Wiki node.
+4. Plan items for these resources MUST set `needs_review=true`, preserve `needs_review_reason`, set `target_path` to the manual confirmation target, and set `action=move`.
+5. Do not leave these items in their original location by default.
+
+Confidence display map:
+
+| Internal Enum | User-Facing Label |
+|---------------|-------------------|
+| `high` | 高，证据明确 |
+| `medium` | 中，有依据但建议确认 |
+| `low` | 低，需要人工确认 |
+
+### Plan Pagination
+
+| Output Area | Rule |
+|-------------|------|
+| Plan details | Show at most 20 plan items per page |
+| Plan item count > 20 | MUST paginate; do not output all details at once |
+| Plan item count > 500 | First response MUST show overview and filters only; no detail rows until user asks |
+| Pagination | Affects display only; complete `plan_items` MUST remain internal |
+
+### Target Tree And Plan Overview
+
+```text
+建议目标目录结构
+
+<target_tree>
+
+移动 / 创建计划总览
+
+本次计划共 <total_count> 项：
+- 创建目录 / 节点：<create_count> 项
+- 移动资源：<move_count> 项（其中来源目录本体：<source_container_move_count> 项）
+- 保持不变：<keep_count> 项
+- 待人工确认：<review_count> 项
+- 高置信度：<high_count> 项
+- 中置信度：<medium_count> 项
+- 低置信度：<low_count> 项
+
+你可以选择：
+1. 查看第 1 页明细
+2. 只看将创建的目录 / 节点
+3. 只看待人工确认项
+4. 只看高置信度移动项
+5. 进入下一步：确认执行计划
+```
+
+If `total_count > 500`, say:
+
+```text
+计划较大，我先只展示总览。
+```
+
+### Plan Revision Protocol
+
+When the user corrects or adjusts the plan in `PLAN_GENERATION` or `EXEC_CONFIRM`, the agent MUST treat it as a full-plan revision unless the user explicitly asks to execute only the corrected items.
+
+Revision triggers include:
+
+- Adjusting classification rules.
+- Adjusting target folder / Wiki node structure.
+- Changing one or more resources' target paths.
+- Excluding resources from movement.
+- Restricting execution to high-confidence items.
+- Moving a whole category to another target.
+- Changing manual confirmation handling.
+- Changing source container cleanup or retention handling.
+
+Internal rules:
+
+1. Record the user correction in `last_user_correction`.
+2. Mark the previous `plan_items` as stale.
+3. Recompute `classification_rules`, `target_tree`, and complete `plan_items` when needed.
+4. Increment `plan_version`.
+5. Set `active_plan_items` to the complete revised plan.
+6. Append a short internal summary to `plan_revision_history`.
+7. Do not execute stale `plan_items`.
+8. Do not execute only the delta unless the user explicitly asks for partial execution.
+
+User-facing output:
+
+```text
+已按你的修改重新生成完整计划。
+
+已应用的修改：
+- <correction item 1>
+- <correction item 2>
+
+当前完整计划：
+- 创建目录 / 节点：<create_count> 项
+- 移动资源：<move_count> 项
+- 保持不变：<keep_count> 项
+- 待人工确认：<review_count> 项
+
+说明：后续执行默认基于这份完整修正版计划，不是只执行刚才的修正项。
+
+你可以选择：
+1. 查看修正版计划总览
+2. 查看本次修改涉及的资源
+3. 进入下一步：确认执行计划
+4. 继续调整
+```
+
+If the user explicitly asks to execute only the corrected items, ask for confirmation before execution:
+
+```text
+你明确要求只执行本次修改涉及的 <count> 项。其余计划项不会执行。
+请确认是否只执行这些项？
+```
+
+### Plan Detail Page
+
+```text
+移动 / 创建计划，第 <page>/<total_pages> 页，每页 20 项
+
+| 序号 | 当前位置 | 标题 | 类型 | 目标位置 | 动作 | 原因 | 置信度 | 待确认原因 |
+|------|----------|------|------|----------|------|------|--------|------------|
+
+还有 <remaining_pages> 页未展示。
+
+你可以回复：
+1. 继续看下一页
+2. 只看待人工确认项
+3. 只看低置信度项
+4. 进入下一步：确认执行计划
+```
+
+## State: EXEC_CONFIRM
+
+Entry: user asks to view execution confirmation or continue toward execution.
+
+MUST:
+
+1. Show write-operation summary:
+   - 将创建哪些目录 / 节点
+   - 将移动哪些资源
+   - 将移动哪些来源目录本体（如有）
+   - 哪些资源仍需人工确认
+   - 预计影响范围
+2. Use `active_plan_items` from the latest complete plan.
+3. Show `Permission Inheritance Notice`.
+4. Ask for execution scope using `Execution Confirmation`.
+5. Reference `Non-goals` for operations excluded from this workflow.
+6. Wait for explicit confirmation.
+
+### Permission Inheritance Notice
+
+Before execution confirmation, MUST show this notice:
+
+```text
+权限提示：移动资源后，资源权限可能随目标位置变化，可见范围或协作权限可能变化。本 workflow 不会自动修改权限。
+```
+
+### Execution Confirmation
+
+When the user wants execution, ask for execution scope:
+
+Execution confirmation options MUST be numbered by currently available choices. Do not show disabled choices, and do not ask the user to reply with skipped numbers.
+
+If a plan detail page is currently active:
+
+```text
+请确认执行范围：
+
+1. 执行完整计划：<total_count> 项
+2. 只执行当前页：<current_page_count> 项
+3. 只执行高置信度项：<high_confidence_count> 项
+4. 暂不执行，只保留方案
+
+本 workflow 只执行已确认范围内的创建、移动和必要的单资源权限申请；不会重命名任何资源。
+```
+
+If no plan detail page is currently active:
+
+```text
+请确认执行范围：
+
+1. 执行完整计划：<total_count> 项
+2. 只执行高置信度项：<high_confidence_count> 项
+3. 暂不执行，只保留方案
+
+如需只执行某一页，请先查看计划明细页。
+
+本 workflow 只执行已确认范围内的创建、移动和必要的单资源权限申请；不会重命名任何资源。
+```
+
+If there is no pagination, still state the total number of plan items covered by confirmation.