RFC: Mitsein agent + generic document workflow template (generate & edit with diff) #228
Closed
opened 2026-05-13 03:10:45 +00:00 by jiayi
·
2 comments
No Branch/Tag Specified
main
chore/migrate-ocas
retrospect/fix-committer-tea
retrospect/solve-issue-fixes
fix/517-expand-skill
fix/574-silent-fail-handling
fix/573-unify-cas-store
fix/571-current-role
fix/567-trim-leading-whitespace
fix/566-adapter-json-stdout
fix/544-remove-legacy-frontmatter
fix/553-edge-prompt-empty
fix/557-step-show-json-escape
fix/559-thread-show-status
fix/561-thread-start-cwd-option
fix/558-thread-edge-location
fix/531-config-mask-apikey
fix/532-config-key-validation
fix/533-double-prefix
fix/551-hermes-bin-engines
fix/549-commit-scope
feat/541-skill-developer
feat/539-skill-author
feat/538-skill-user
feat/540-skill-actor
fix/ci-skip-integration-tests
fix/535-sqlite-fallback
fix/531-532-533
fix/528-refactor-apikey
fix/526-config-subcommand
fix/522-cancelled-thread-status
fix/523-bin-entry-point
fix/519-read-session-file
fix/enum-multi-exit-validation
fix/remove-chinese-cli-output
feat/424-setup-agent-discovery
fix/hermes-integration-test-import
fix/449-reduce-dashboard-complexity
refactor/512-rename-packages
chore/510-open-source-readiness
chore/solve-issue-portable
fix/489-step-timing
fix/506-semantic-validation
feat/502-oneOf-output-instruction
feat/499-phase2-discriminated-union
feat/499-dollar-status
fix/497-update-docs
feat/490-phase3-dashboard
feat/490-phase2-yaml-migration
feat/490-status-routing
fix/487-refactor-step-read
fix/484-step-read-command
fix/480-thread-read-quota
fix/481-cas-has-exit-code
fix/474-tea-pr-worktree-fix
fix/469-step-commands-completed-threads
fix/473-first-time-role-context
fix/471-thread-list-filters
fix/466-continuation-prompt-content
chore/cleanup-cli-docs
fix/463-http-methods
fix/464-worktree-isolation
fix/461-per-agent-session-cache
fix/459-xml-tag-isolation
fix/444-biome-complexity-warnings
fix/456-thread-step-background
fix/448-reduce-complexity
fix/445-reduce-setup-complexity
fix/446-reduce-thread-complexity
docs/sync-readme
fix/447-reduce-loop-complexity
fix/439-detail-merge-and-acp
fix/440-thread-read-prompt-dedup
fix/builtin-session-lifecycle
debug/439-raw-ndjson-dump
fix/428-multi-strategy-workflow-resolution
fix/yaml-no-alias
feat/428-workflow-resolution
feat/turn-jsonl-session
feat/426-builtin-session-resume
fix/builtin-agent-system-user-split
feat/422-claude-code-detail-enrichment
feat/builtin-agent
test/418-resume-e2e-repro
chore/update-cli-reference
fix/413-log-subcommands
feat/411-process-logger
feat/405-phase2-find-last-role-index
feat/405-edge-prompt-required
feat/402-edge-prompt-session-resume
feat/398-hermes-acp-client
fix/395-worktree-hygiene
feat/391-workflow-agent-claude-code
jshang/workflow-dashboard
fix/394-forbid-extra-frontmatter-fields
feat/335-setup-validate-model
fix/389-dynamic-format-instruction
fix/388-frontmatter-dynamic-fields
fix/385-revert-output-protocol
feat/384-agent-session-protocol
feat/remove-llm-extract
feat/cas-put-text
fix/380-hermes-quiet-flag
feat/373-thread-step-count
fix/fallback-transition-validation
feat/376-first-last-jsonata
refactor/374-meta-to-frontmatter
feat/370-solve-issue-workflow
feat/369-uwf-skill-cli
chore/ignore-legacy-biome
feat/365-project-local-workflows
refactor/364-rename-role-fields
feat/359-role-four-phase
chore/rename-uwf-to-workflow
chore/repo-restructure
feat/357-thread-read-content
feat/355-uwf-frontmatter
feat/351-phase3-prompt-focus
feat/351-phase2-adapter-frontmatter
feat/351-frontmatter-markdown-phase1
feat/349-thread-read
fix/348-session-id-stderr
fix/342-parse-session-id
fix/342-fork-simplify
feat/342-thread-steps-fork
refactor/simplify-agent-context
refactor/pass-store-via-context
feat/337-agent-detail-merkle
feat/cas-reindex
refactor/use-list-by-type
refactor/merge-cas-get-cat
refactor/remove-table-format
fix/328-table-vertical
user/jiayiyan/feat_office-agent-document-template-v2
feat/328-format-option
fix/319-cas-json-output
fix/319-validate-schema-only-inline
fix/319-schema-titles
feat/319-uwf-cas-builtin
user/jiayiyan/feat_office-agent-document-template
feat/309-uwf-stateless
feat/285-phase3-x-cas-ref
chore/remove-old-templates
feat/294-phase7-cli
private/json-cas-refactor
feat/294-phase5-react-layer
feat/294-phase4-engine-migration
feat/294-phase3-workflow-json
feat/294-jsonata-moderator
docs/architecture-cards
feat/285-phase2-remove-extractrefs
feat/285-cas-ref-annotation
chore/fix-biome-complexity-warnings
refactor/agent-fn-required-opt
chore/audit-exports-cleanup
chore/remove-symlink-dead-code
chore/no-external-bundle
feat/show-system-prompt
chore/205-env-example
chore/biome-fix-and-pre-push-hook
chore/remove-parentRequired-param
fix/265-flaky-thread-rm
feat/workflow-detail-layout
chore/252-remove-text-adapter
feat/261-adapter-migration
feat/252-agent-fn
feat/graph-interactions
fix/dashboard-graph-side-handles
fix/dashboard-graph-visual-247
fix/cursor-agent-runtime-extract
refactor/serve-remove-http-tunnel
chore/slim-role-output
feat/changesets-version-management
chore/bump-0.4.0
chore/merge-publish-scripts
chore/remove-link-all
feat/merge-publish-scripts
fix/auto-discover-publish
refactor/dashboard-custom-spine-layout
fix/cli-bin-path
fix/dashboard-elk-review-feedback
feat/dashboard-elk-layout
fix/skill-author-pitfalls
fix/publish-lockfile-regen
feat/210-ws-gateway-phase2
refactor/thread-detail-side-by-side-layout
feat/210-ws-gateway-phase1
feat/222-tools-smoke-test-phase3
feat/222-react-adapter-phase2
feat/222-adapter-fn-phase1
fix/219-review-followup
feat/216-setup-and-build-scripts
fix/206-bundle-build-register
feat/197-agent-observability
feat/198-dashboard-workflow-graph
feat/194-merkle-call-stack-phase2
refactor/200-moderator-table
feat/194-merkle-call-stack-phase1
feat/cursor-agent-workspace-extract
fix/191-dashboard-thread-sort
feat/187-end-node-llm-summary
refactor/185-remove-max-rounds
refactor/180-simplify-extract-fn
feat/177-gateway-route-reorg
feat/172-declarative-moderator-table
fix/170-thread-status-detection
feat/164-cf-worker-gateway
fix/161-162-cas-content-refs
feat/155-cas-thread-phase-5
feat/155-cas-thread-phase-4
feat/155-cas-thread-phase-3
feat/155-cas-thread-phase-2
feat/155-cas-thread-phase-1
chore/rename-dashboard-folder
refactor/143-split-packages
feat/139-thread-reactor
refactor/runtime-descriptor-boundary
fix/128-dashboard-enhancements
fix/130-sse-incremental
fix/120-serve-hardening
feat/131-dashboard-sse
refactor/thread-context-runtime
feat/118-serve-write-sse
feat/118-dashboard
refactor/121-split-workflow-runtime
feat/118-serve-api
chore/bump-0.2.0
feat/110-phase3-supervisor
chore/114-remove-deprecated
feat/110-phase2-migrate-extract
docs/package-readmes
feat/110-phase1-config-layer
chore/108-cli-module-discipline
chore/106-workflow-module-discipline
chore/cleanup-cas-thread-id
refactor/102-module-folders
refactor/97-phase4-cleanup
refactor/96-phase3-split-dispatch
refactor/95-phase2-control-merge
chore/remove-build-scripts
refactor/93-phase1-directory-restructure
feat/91-reviewer-prompt
docs/88-readme-architecture-cleanup
fix/85-usage-format
fix/83-cli-ux
feat/81-skill-topics
fix/75-nits
refactor/75-merge-roles-phase1
refactor/71-auto-gen-skill-doc
feat/63-workflow-storage-root
feat/69-help-skill
refactor/cli-noun-verb-grouping
feat/59-solve-issue-refactor
feat/37-live-command
feat/58-develop-workflow
feat/36-init-command
feat/44-react-extract
feat/43-extract-provider-config
feat/42-thread-root-node
feat/41-merkle-content-cas
feat/33-workflow-as-agent
feat/32-cas-gc
feat/31-refs-tracking
feat/30-global-cas
feat/28-preparer-role
fix/26-planner-cas-cli-prompt
test/19-validate-workflow-descriptor
feat/23-phase-title-in-planner-meta
fix/21-moderator-coder-transition
fix/review-feedback-and-typecheck
fix/type-errors-and-tsbuildinfo
No results found.
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
aobing
jiashuang (Jia Shuang)
jiayi (Jiayi)
luming
scottwei
tuanzi
xiaoju
xiaomo
xiaonuo
xingyue
Clear assignees
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: uncaged/workflow#228
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
设计文档:文档生成/编辑 Workflow 体系
日期: 2026-05-13
概述
本设计分三层,实现通过 mitsein 生成或编辑 Word 文档的完整 workflow 体系:
@uncaged/workflow-agent-mitseinpackages/workflow-agent-mitsein/@uncaged/workflow-agent-docx-diffpackages/workflow-agent-docx-diff/@uncaged/workflow-template-documentpackages/workflow-template-document/mitsein-doc(示例名)xingyue-workflows/)Template 只定义结构,不含任何执行逻辑。执行器与 template 解耦:任何能生成/编辑文档的 agent 均可绑定
writer角色,任何能产出 diff 报告的 agent 均可绑定differ角色。一、
workflow-agent-mitsein通用 mitsein 执行器,与
workflow-agent-cursor、workflow-agent-hermes平级。接收 role definition + thread context,通过 mitsein CLI 执行任务,返回结果。不含业务判断逻辑,不做 docx-diff。执行流程
--prompt传入的是MitseinStartInput.prompt(从ctx.start.contentJSON 解析)。RoleDefinition.systemPrompt在 mitsein agent 中不使用。说明:
delegate get取完整快照提取 file_id,规避 SSE payload schema 不确定性--timeout 600为最长等待上限(10 分钟),超时视为失败inputDocx须为调用方环境下的有效绝对路径,路径有效性由调用方保证输出目录:
~/.uncaged/workflow/outputs/<thread_id>/包结构
依赖
@uncaged/workflow-protocolResult、ok、err@uncaged/workflow-utilcreateLogger、storage path 工具函数运行时依赖
mitseinCLI 在 PATH 中可用。二、
workflow-agent-docx-diffdiffer角色的专用执行器,与workflow-agent-mitsein平级。读取ctx.steps中的WriterMeta,调用docx-diffCLI 生成差异报告,返回DifferMeta。执行流程
包结构
依赖
@uncaged/workflow-protocolAgentFn、AgentContext@uncaged/workflow-template-documentWriterMeta、DifferMeta类型运行时依赖
docx-diffCLI 在 PATH 中可用(仅编辑模式)。三、
workflow-template-document通用文档生成/编辑流程模板,不绑定任何具体 agent。定义两个角色和调度表。
前提假设: 本设计假设 workflow 在本机执行,
inputDocx绝对路径在运行环境中有效。跨机器或远端执行不在当前范围内。Thread 启动输入
角色与 Meta
调度表
differ角色由@uncaged/workflow-agent-docx-diff提供的createDocxDiffAgent()执行,直接调用本地docx-diffCLI,不经过 LLM:bundle 中通过
AgentBinding.overrides绑定:overrides: { differ: createDocxDiffAgent() }。包结构
依赖
@uncaged/workflow-runtimeRoleDefinition、ModeratorTable、START、END@uncaged/workflow-protocolResult、ok、err@uncaged/workflow-utilcreateLogger运行时编辑模式依赖
docx-diffCLI 在 PATH 中可用。四、Bundle(外部 workspace)
在外部 workspace(如
xingyue-workflows/)中组合上述两个包,生成可注册执行的.esm.jsbundle。Build 命令:
bun run build:develop→ 产出单文件.esm.js注册与执行:
不在范围内
differ角色的 HTML/terminal 格式输出(仅 docx)星月的 Review 🌙
整体印象:设计很干净 👍
三层分离(执行器 / 模板 / Bundle)思路清晰,和现有
workflow-agent-cursor、workflow-agent-hermes平级,架构一致性很好。亮点
START → writer →(edit)→ differ → END,生成模式直接跳过 differ几个问题 🤔
1. 轮询策略没定义
runner.ts第 3 步「轮询delegate get直到 completed」,但没说间隔、超时、最大重试。Mitsein 一次文档生成可能几十秒到几分钟,建议明确写一个退避策略(比如 2s → 5s → 10s,总超时 5min)。2. differ 的执行器是谁?
说了「由 shell 执行器驱动,不经过 LLM」,Bundle 示例里写
differ: shellAgent,注释说「由workflow-execute或workflow-util-agent提供的 shell 执行器」。这个shellAgent目前存在吗?如果不存在,是不是要先实现?建议在 RFC 里明确是复用现有还是新建。3. 错误路径不够细
mitsein uploads create失败怎么办?(文件不存在 / 网络超时)delegate submit成功但delegate get最终状态是failed?docx-diffCLI 返回非零?建议至少列一下每个步骤的 error → Result.err 映射,不然实现的人要猜。
4. 建议分 Phase + 开 Testing Issue
按我们的惯例,RFC 落地建议拆成:
workflow-agent-mitsein包 scaffold + runner 封装workflow-template-document包 + moderator每个 Phase 开一个 Testing Issue 带具体验证步骤,方便 review。
5.
inputDocx用绝对路径的风险DocumentStartInput.inputDocx写的是「绝对路径」,跨机器执行时路径会失效。考虑用相对于 workflow workspace 的路径,或者统一走 uploads?总结:设计本身没问题,补上轮询策略和错误处理就可以开干了 💪
Re-review 🌙
伽艺哥哥更新得很到位,我之前提的 5 个问题逐个过一下:
✅ 已解决
1. 轮询策略 → 改成了
delegate events --filter completed,failed --timeout 600SSE 事件流阻塞等待,比轮询优雅多了!超时 10 分钟也合理。👍2. differ 执行器 → 拆成了独立的
@uncaged/workflow-agent-docx-diff包,有自己的createDocxDiffAgent(),不再含糊地引用shellAgent。Bundle 里通过overrides: { differ: docxDiffAgent }绑定,清晰。👍3. 错误路径 → 明确了「CLI 不在 PATH 或 run 失败均视为不可恢复错误,直接 throw」,docx-diff 也说明了 exit code 语义(0=无变更,1=有变更,2+=错误)。够用了。👍
5. 绝对路径 → 加了前提假设「本设计假设 workflow 在本机执行,inputDocx 绝对路径在运行环境中有效。跨机器或远端执行不在当前范围内」。scope 界定清楚,OK。👍
📋 还没提到
4. 分 Phase + Testing Issue — RFC 本身不需要写这个,但建议开工前先拆好。
结论:LGTM 🚀 可以开干了!