From 8265c8f4a9f94fc6b71ff2dba63a13d8af564058 Mon Sep 17 00:00:00 2001 From: Yige Date: Tue, 1 Sep 2026 07:40:21 -0400 Subject: [PATCH] feat(workforce-optimization): governed nonexpert clarification and evidence (#106) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 摘要 / Summary 补问、原话解释与真人确认分离；增加版本能力预检、sourceField/evidenceLinks、有限语义用例及正确工件依赖顺序。 Separate answers, interpretation and human confirmation; add capability discovery, explicit source/evidence bindings, finite semantic checks and artifact ordering. 发现描述覆盖“仅澄清”入口；有歧义的原话保持缺口，不把“不确定”塞入精确枚举或规范化值。按当前对话语言加载框架与固定事实门尾注。 当前请求中已唯一确定的值会写成类型化、待真人确认的 `node.value`；只有未知或仍有歧义的事实才保持 `needs_input`。 Discovery covers clarify-only requests. Ambiguous raw answers remain unresolved, rather than becoming exact placeholder values. The framework and fixed fact-gate footer follow the current conversation language. Exact values uniquely supplied by the current request become typed, human-reviewable `node.value` proposals; only genuinely unknown or ambiguous facts remain `needs_input`. 应用/服务重启或重试 fork 后，入口必须在当前父轮重新加载 Skill，并在委派前用 ToolCatalog 核实阶段工具；子 Agent 不得突破未激活父级的能力上限。 After an app/service restart or retry fork, the entry Agent reloads the Skill in the current parent turn and verifies stage tools before delegation; a child never expands an unactivated parent ceiling. 新的 decision-grade `OptimizationSpec` 强制使用 v2，并完整声明 `semantic_contract` 中的 solve intent 及所有 objective/variable/constraint/data reference 的单位/维度；legacy v1 仅只读兼容。 New decision-grade `OptimizationSpec` artifacts use v2 and a complete semantic contract for solve intent plus every material objective, variable, constraint and data reference; legacy v1 remains read-only compatibility. ## 验证 / Validation - Scoped Skill/i18n/catalog check passes with zero errors. Existing repository warnings remain. - Publication safety check passed, including hidden working-tree files, new paths, branch/commit metadata and collaboration text. - 双语说明与 source hash 已同步，版本更新为 2.7.0；缺少新平台契约时保持普通澄清，不模拟缺失门禁。 - Bilingual bodies and source hashes are synchronized at version 2.7.0. Older clients stay in plain-text clarification when capability discovery fails. ## 状态 / Status Runtime acceptance is still in progress; draft only. No customer data, credentials, solver software or deployment settings are included. 真机验收仍在进行，本 PR 暂为草稿。保留外部求解器许可证、部署和费用披露；本变更不包含求解器、客户数据或凭据。 --------- Co-authored-by: yige --- scripts/i18n/test_validate_i18n.py | 47 +++++++++++++++++++ skills/workforce-optimization/SKILL.md | 47 +++++++++++++------ skills/workforce-optimization/SKILL.zh-CN.md | 27 +++++++++-- .../catalog-metadata.v1.json | 10 ++-- .../requirement-clarification-framework.md | 2 + ...quirement-clarification-framework.zh-CN.md | 2 + 6 files changed, 112 insertions(+), 23 deletions(-) diff --git a/scripts/i18n/test_validate_i18n.py b/scripts/i18n/test_validate_i18n.py index 7397a12..a714565 100644 --- a/scripts/i18n/test_validate_i18n.py +++ b/scripts/i18n/test_validate_i18n.py @@ -207,6 +207,53 @@ class PublishableTeamCatalogTests(unittest.TestCase): with tempfile.TemporaryDirectory() as tmp: with patch.object(VALIDATOR, "REPO_ROOT", Path(tmp)): self.assertEqual([], VALIDATOR.count_publishable_teams()) +class WorkforceClarificationDiscoveryTests(unittest.TestCase): + """Guard the catalog-only entry text; actual model selection still needs runtime acceptance.""" + + def test_clarify_only_requests_are_explicit_in_both_discovery_locales(self) -> None: + import json + import yaml + + directory = Path(__file__).resolve().parents[2] / "skills" / "workforce-optimization" + raw = (directory / "SKILL.md").read_text(encoding="utf-8") + metadata = yaml.safe_load(raw.split("---", 2)[1]) + locales = metadata["metadata"]["i18n"] + catalog = json.loads((directory / "catalog-metadata.v1.json").read_text(encoding="utf-8")) + # Keep the repository's on-demand-body policy; don't enable eager injection of all Skills. + self.assertIs(metadata["disable-model-invocation"], True) + self.assertIn("只澄清", metadata["description"][:180]) + self.assertIn("Skill", metadata["description"][:180]) + for locale, trigger in (("zh-CN", "暂不求解"), ("en-US", "clarify only")): + description = locales[locale]["description"] + self.assertIn(trigger, description) + self.assertIn("DecisionWorkspace", description) + self.assertIn("AskUserQuestion", description) + self.assertEqual(description, catalog["presentation"]["i18n"][locale]["description"]) + self.assertIn("clarification works without a connected solver", metadata["compatibility"]) + self.assertIn("separately", metadata["compatibility"]) + self.assertIn("Generic AskUserQuestion may handle non-modeling setup", raw) + chinese = (directory / "SKILL.zh-CN.md").read_text(encoding="utf-8") + self.assertIn("普通 AskUserQuestion 只用于非建模设置选择", chinese) + + def test_ambiguous_answers_and_current_language_keep_their_boundaries(self) -> None: + directory = Path(__file__).resolve().parents[2] / "skills" / "workforce-optimization" + english = (directory / "SKILL.md").read_text(encoding="utf-8") + chinese = (directory / "SKILL.zh-CN.md").read_text(encoding="utf-8") + self.assertIn("only if raw_text uniquely determines", english) + self.assertIn("keep the original answer and needs_input", english) + self.assertIn("Do not add epistemic placeholders", english) + self.assertIn("proposals must include a typed `node.value`", english) + self.assertIn("for Chinese use [中文澄清框架]", english) + # 以下断言分别覆盖中文规范化、未知与语言入口。 + self.assertIn("仅在 raw_text 能唯一确定业务值及必要单位/统计窗口时", chinese) + self.assertIn("仍有歧义时保留原答案和 needs_input", chinese) + self.assertIn("不得把“目前不确定”“不知道”等知识缺口", chinese) + self.assertIn("提议节点必须写入类型化 `node.value`", chinese) + self.assertIn("技能 metadata 默认语言不覆盖用户语言", chinese) + for locale in ("", ".zh-CN"): + framework = (directory / "references" / f"requirement-clarification-framework{locale}.md").read_text(encoding="utf-8") + self.assertIn("needs_input", framework) + self.assertIn("node.value", framework) if __name__ == "__main__": diff --git a/skills/workforce-optimization/SKILL.md b/skills/workforce-optimization/SKILL.md index ffcab82..4e80221 100644 --- a/skills/workforce-optimization/SKILL.md +++ b/skills/workforce-optimization/SKILL.md @@ -1,10 +1,10 @@ --- name: workforce-optimization description: >- - Use this Skill when a user naturally asks about workforce efficiency, staffing, shifts, service coverage, hierarchical resource allocation, performance targets, centralized task scheduling, operations research, or general LP/MILP. Govern the request through DecisionWorkspace, versioned multi-agent artifacts, guarded compile/solve, independent validation, and human approval. MindOptSolve is only a compatible connector Tool: the MindOpt solver software, applicable license, separate deployment, and related fees are external and not bundled. 用户自然提到人效、人员配置、排班、服务范围、资源划分、绩效目标、任务调度、运筹优化或 LP/MILP 时使用；通过 DecisionWorkspace、人机确认、版本化制品、受保护求解、独立验收和真人批准完成治理；MindOpt 软件、适用许可证、独立部署及费用不随本技能或客户端提供。 + 排班、工时上限、人员配置的第一轮澄清（含“只澄清、暂不求解”）也先用 Skill 工具加载本技能，再用 DecisionWorkspace 补问和真人确认卡；普通 AskUserQuestion 不能代替业务事实闭环。Load this Skill for the first clarification of staffing, shifts, work-hour limits, service coverage, resource allocation, targets, task scheduling or LP/MILP, including clarify only / do not solve yet requests. Use DecisionWorkspace question and human-confirmation cards for model-changing facts; generic AskUserQuestion is not a substitute. Clarification needs no connected solver. Actual MindOpt solving requires a separately licensed/deployed solver and configured connector; software, licenses, hosting and fees are not included. MindOpt 软件、许可证、部署及相关费用需使用方另行取得或承担。 compatibility: >- - Requires a separately installed or deployed MindOpt solver, a valid license obtained under the official terms, and configured solver.mindopt connections; commercial licenses and operating costs are purchased separately when applicable. 需要外部安装或部署 MindOpt、按官方条款取得有效许可证并配置 solver.mindopt 连接；适用的商业许可及运行费用需另行采购承担。 -version: 2.3.4 + Requirement clarification works without a connected solver. Actual MindOpt solving requires separately installed or deployed MindOpt, a valid license under its official terms, and configured solver.mindopt connections; commercial licenses and operating costs are separate when applicable. 需求澄清不要求先连接求解器；实际 MindOpt 求解仍需外部安装部署、有效许可证及 solver.mindopt 连接，适用的商业许可和运行费用另行承担。 +version: 2.9.0 type: procedural risk_level: medium status: enabled @@ -25,7 +25,7 @@ provides: - OptimizationValidate metadata: author: workforce-optimization-team - updated_at: '2026-08-29' + updated_at: '2026-09-01' i18n: default_locale: en-US source_locale: zh-CN @@ -36,18 +36,18 @@ metadata: name: 人效与资源优化 short_desc: 用决策工作区共管人效建模、受保护求解与独立验收；MindOpt 需外部授权部署 description: >- - 当用户自然提出服务范围、分层资源分配、绩效目标、集中任务调度、人员配置、排班或通用 LP/MILP 需求时，通过 DecisionWorkspace 的人机确认、精确版本制品、入口 Agent 绑定、同伴审阅、执行门禁、独立验收和真人批准形成可恢复治理链。选择 MindOpt 引擎时，实际求解仍依赖使用方另行取得适用许可证、部署并接入 MindOpt；客户端和本技能不包含求解器软件、许可证、算力托管或相关费用。 + 用户提出排班、工时上限、人员配置、服务覆盖、资源分配、绩效目标、任务调度或 LP/MILP，即使“只澄清、暂不求解”，也先用 Skill 工具加载本技能。影响模型的事实使用 DecisionWorkspace 补问及真人确认卡，不能用普通 AskUserQuestion 代替。澄清无需连接求解器；实际 MindOpt 求解需使用方另行取得适用许可证、部署并配置连接，软件、许可证、算力托管及费用均不包含在技能中。 body: ./SKILL.zh-CN.md - source_hash: sha256:63c40f1123d9fc31 - translated_by: human + source_hash: sha256:0be8b9c17e844f9d + translated_by: ai:codex en-US: name: Workforce and Resource Optimization short_desc: Co-manage workforce models, guarded solving, and independent validation; MindOpt is externally licensed description: >- - When users naturally request service coverage, hierarchical resource allocation, performance targets, centralized task scheduling, staffing, shift planning, or general LP/MILP, use DecisionWorkspace human confirmation, exact-version artifacts, entry Agent binding, peer review, execution guards, independent validation, and human approval to create a recoverable governance chain. When MindOpt is selected, actual solving still requires the user to obtain an applicable license, deploy MindOpt, and configure its connector; the client and this Skill do not include the solver, license, hosted compute, or related fees. + Load this Skill for the first clarification of staffing, shifts, work-hour limits, service coverage, resource allocation, targets, task scheduling or LP/MILP, including clarify only / do not solve yet requests. Use DecisionWorkspace question and human-confirmation cards for model-changing facts; generic AskUserQuestion is not a substitute. Clarification needs no connected solver. Actual MindOpt solving requires a separately licensed/deployed solver and configured connector; software, licenses, hosting and fees are not included. body: ./SKILL.md - source_hash: sha256:63c40f1123d9fc31 - translated_by: human + source_hash: sha256:0be8b9c17e844f9d + translated_by: ai:codex market: icon: >- @@ -74,7 +74,8 @@ Turn natural-language workforce-efficiency requests into reviewable and recovera - The platform retains direct personal `MindOptSolve` and compile-option overrides only as a backward-compatible, non-decision-grade expert path outside this Skill's governed team workflow. Never present an unbound personal call as reviewed, human-confirmed, recoverable, or decision-grade; team runs must use the guarded `OptimizationSolve` path and solver limits recorded in the committed specification. - Before promising or requesting an actual solve, verify that the external connector is configured and ready, required capabilities are available, and the deployment has a valid applicable license. A registered Tool name alone is not evidence that the solver is installed, licensed, reachable, or paid for. - If the external dependency is unavailable, state which prerequisite is missing and stop before the solver call. You may still finish requirement clarification and produce reviewable `SceneSpec`, `DataContract`, and `OptimizationSpec` artifacts for later execution, but must not fabricate a `SolveResult`, feasibility, optimality, or benefit claim. -- Before routing or modeling, the natural-language entry Agent must read the [requirement-clarification framework](references/requirement-clarification-framework.md) in full and follow its real-decision, mandatory-question, and conditional-question branches. +- Before routing or modeling, read the framework matching the user's current conversation language in full: for Chinese use [中文澄清框架](references/requirement-clarification-framework.zh-CN.md), and for English use the [English framework](references/requirement-clarification-framework.md). Follow its real-decision, mandatory-question and conditional-question branches. The Skill's default metadata locale does not override the user's language; use that framework's matching-language fixed footer. +- Skill activation is intentionally scoped to the current service-process lifetime and active parent turn. After an app/service restart or retry fork, the current entry Agent must load this Skill again before checking hidden optimization tools or delegating a stage owner; verify `TeamArtifact` and the stage-required optimization tools in `ToolCatalog` before delegation. A child Agent loading the Skill cannot expand a ceiling inherited from an unactivated parent. Do not persist activation, widen default tools, switch source/scope to evade the ceiling, or ask a child to fabricate artifacts when capability is absent. - First read the AgentFS user profile, preferences, and relationship memories already injected into the current context. Choose professional, business-guided, or evidence-insufficient adaptive language only from user-confirmed, current, non-conflicting evidence about expertise or communication preference. Employer, job title, one use of jargon, or model inference is not sufficient evidence. - Professional language may expose the complete structured information contract at once and accept a batch answer. Business-guided language uses plain-language groups in impact order for as many turns as needed. When evidence is insufficient, show a neutral coverage outline and ask the user's preference. Every mode maintains the same complete question map; never omit a model-changing item merely to reduce turns, question count, or cognitive load. - End every first response with the two-sentence fixed fact-gate footer defined by the requirement-clarification framework. Do not paraphrase, shorten, merge, or omit either sentence. @@ -82,25 +83,43 @@ Turn natural-language workforce-efficiency requests into reviewable and recovera - Treat relative business-time expressions such as today, tomorrow, the next N days, or this quarter as `pending_confirmation` until the current request confirms the business timezone, business calendar, date-time anchor, and applicable day-boundary, cutoff, holiday, and overnight rules. A system clock or host timezone is environment evidence, not a business rule. - Isolate every new request from historical contamination. Facts from another conversation, Plan, artifact, memory, or sample remain `pending_confirmation` until the user explicitly carries them into the current request; do not search for or reuse a semantically similar Plan as evidence for the first response. - Use one entry Agent for routing, consolidated questions, and final delivery. Assign one owner to each stage. +- Clarify-only requests still use this workflow. Generic AskUserQuestion may handle non-modeling setup choices or an explicitly explained capability fallback, but its replies never become DecisionWorkspace answers or human confirmations. +- Before using the nonexpert workflow, inspect the live DecisionWorkspace schemas for semantic_checks_version, request_clarification, interpret_clarification, sourceField and evidenceLinks, and confirm check_semantics is available. If the client lacks these contracts, remain in clarification and explain that a compatible client is required. Never emulate missing gates by editing AgentFS records or using the personal solver path. +- Preflight with a read-only DecisionWorkspace list call. If global TaskBoard/assistance capability is disabled or unavailable, explain the missing user interaction surface and remain in plain-text clarification; do not create questions the user cannot answer, and do not enable capabilities without their request. +- Clarification itself may create a team workspace with semantic_checks_version=1, propose business nodes, inspect an explicitly authorized data source, and record request_clarification before the fact gate passes. These are clarification operations, not permission to build a mathematical model, publish modeling artifacts, delegate solving or call a solver. +- Ask model-changing gaps through request_clarification with an answerable question, reason, canonical type, declared unit and justified constraints. Keep the same logical question while its statement/constraints remain unchanged. Do not invent bounds to reduce choices. Group questions by business impact and explain the remaining coverage in ordinary language. +- The platform already offers unknown and raw_text response channels. Do not add epistemic placeholders such as "not sure yet" or "unknown" to exact choices or node.value. These describe missing knowledge, not a business option. Explain the reason without repeating the UI's "why ask" label. +- When the current user message uniquely supplies a complete business value and every required unit/window, proposals must include a typed `node.value` and remain proposed until the dedicated human confirmation. An Agent-proposed value is not an Agent confirmation. Omitting value incorrectly downgrades a known fact to needs_input; a summary-only node is not a confirmable statement. Omit value only for genuinely unknown or still-ambiguous facts and ask a clarification instead. +- Human value answers are proposed, not confirmed. Use interpret_clarification only if raw_text uniquely determines the business value and every necessary unit/time scope. Preserve the original wording and link the normalized node to that answer; the user must explicitly confirm the new statement. If ambiguity remains, keep the original answer and needs_input, explain the remaining gap, and do not call interpret_clarification or fill a canonical placeholder. For example, "about eight hours, not sure per day or week" determines neither an exact limit nor a time window. Never use ordinary upsert to detach the original answer, manufacture a receipt, or default unknown. +- Let the platform continue the original source conversation after its effective gaps settle. Do not poll by starting new messages, change request identities to evade deduplication, revive canceled sources or retry unknown dispatch outcomes. A pending/interpretation signal is not solve authorization; reread the exact workspace and honor all gates. +- Bind real data with an authorized FileResourceRef, bytesHash, exact fields/types/units and confirmed timeScope. Add finite required/unique/range/enum/foreign_key/cutoff rules as applicable. Range/enum constants and FK fields must use consistent units. Every consumed data field must have modelSemantics.sourceField plus a sourced_from relationship before its business quantity is traced into the model. Unused columns need not be modeled. Unit/window conversions require an explicitly transformed, traceable and reconfirmed source; do not change only its unit label. +- Propose blocking validation nodes with confirmed positive, negative and boundary examples for exact model constraints. Include complete candidate assignments and the intended hard/soft behavior. Cover missing constraints, wrong time aggregation and accidental softening. Platform check_semantics independently evaluates the declared examples; a solver result or a second Agent explanation alone does not establish business correctness. +- Every new decision-grade `OptimizationSpec` must use the live TeamArtifact payload branch whose `schema_version` is exactly `2`; legacy v1 payloads are read-only compatibility artifacts and cannot be linked to approve a current decision. Before publishing, read the v2 schema and construct its complete algebraic/CP `model`, `problem_family`, exact `data_refs`, and `semantic_contract`. The contract must declare `solve_intent` and exactly one entry for every material objective, variable, constraint, and data reference actually present, with the confirmed dimension, canonical unit, and time scope where applicable—no missing, unknown, duplicate, display-label, JSON-Pointer, or implicit-unit substitutions. Re-read the published exact revision and verify this closed set before requesting `link_artifact`; a compile-success receipt for legacy or incomplete semantics is not decision-grade evidence. +- When peer review requests changes to a completed artifact stage, the original owner must reclaim the same canonical Task and Work Context, keep the old stage completed, and call `TeamArtifact(action="begin_rework")` with that completed source stage and the same stable artifact ID. Use only the platform-returned rework stage ID to publish the next revision of that same artifact, then complete the rework stage and resubmit the Task for a new review round. Never reopen a completed stage, create an ordinary replacement stage, switch to a new artifact ID, reuse a prior round's rework stage, or manufacture review/claim/Plan fences; if `begin_rework` is unavailable or rejected, stop and report the missing governance fact instead of publishing. +- Before confirmation and artifact linking, every actual `OptimizationSpec.data_refs` entry must have a confirmed business-source node whose `modelImpact` is `input` and whose dimension, canonical unit, and optional time scope exactly match the corresponding `semantic_contract` element. Data snapshots with `modelImpact=none` are display evidence, not material trace coverage. Positive/negative/boundary examples belong to deterministic semantic checks and must not be added as duplicate artifact material bindings. +- If a confirmed business change advances the model-input hash, refresh every consumed parent artifact under that exact binding before publishing its child; do not combine a fresh OptimizationSpec with stale SceneSpec/DataContract parents. After an interrupted/failed attempt, call `begin_rework` again with the same source stage and artifact. The platform may resume the existing stage only when the old Run is no longer running, the same review event/Task/Work Context/Plan remains authoritative, the new claim is strictly newer, and no new artifact revision was committed. Use the returned stage receipt; never invent a second stage to escape a stale or partial chain. +- Attach file evidence with evidenceLinks whose ref matches the node's evidenceRefs; use only authorized FileResourceRef identities, not guessed paths or arbitrary URLs. Explain report failures using their reason code, exact field/model element, frozen expectation, observed value, impact and next safe action. Direct the user to the graph's issue/source/model controls and change-impact preview; a colored branch, viewed evidence or preview never grants execution approval. - After the fact-confirmation gate passes, follow this governed sequence without skipping or reordering its control points: 1. The entry Agent reads the needed `DecisionWorkspace(action="schema")` sections and each `TeamArtifact(action="schema")` contract before constructing writes. 2. The entry Agent creates the team DecisionWorkspace or submits CAS-protected proposals in business language; proposals never manufacture human receipts. 3. The user confirms or rejects blocking facts only through the platform's dedicated human controls. A rejection remains an auditable inactive tombstone. All Agents wait for the authoritative result. 4. Only the top-level entry Agent calls `DecisionWorkspace(action="bind_workspace")` for the validated current workspace revision and model-input hash. Specialists may not bind, replace, or bypass it. - 5. The assigned stage owner publishes `SceneSpec`, `DataContract`, optional `PredictionArtifact`, `OptimizationSpec`, `SolveResult`, `ValidationReport`, and `DeliveryBundle` in dependency order through `TeamArtifact`, retaining the returned exact artifact revision and DecisionWorkspace snapshot. + 5. The assigned stage owners publish `SceneSpec`, `DataContract`, optional `PredictionArtifact`, and a decision-grade OptimizationSpec v2 with the complete `semantic_contract` above in dependency order through `TeamArtifact`, retaining exact artifact revisions and the DecisionWorkspace snapshot. When confirmed predictive inputs require training data, call OptimizationPredict inside this step, publish its real PredictionArtifact and confirm its model-changing outputs before creating OptimizationSpec. Without predictive inputs, omit this branch; do not predict after semantic checks. Initial model publication performs the platform's internal pure compilation checks; do not call guarded OptimizationCompile early to break the model-publication/semantic-check dependency. 6. The entry Agent calls `DecisionWorkspace(action="link_artifact")` with the exact artifact ID, exact revision, and semantic bindings; never resolve governed evidence through `latest`. 7. Submit the linked revision for peer review. An independent reviewer checks business-to-model coverage, units, variable families, feasibility logic, provenance, gaps, and stale/rejected exclusions before execution. + After the user confirms the exact source/rules/examples, call DecisionWorkspace(action="check_semantics") for the current revision/hash and inspect its complete bounded report. Missing data, unsupported evaluators, budget limits or unconfirmed examples are blocked, not passes. Do not rebind the workspace merely because an audit-only revision changed; retain the model-input snapshot until business semantics change. 8. Invoke `OptimizationCompile` and then `OptimizationSolve`; both must pass the platform's DecisionWorkspace execution guard before side effects. `MindOptSolve` remains a compatible connector name and must never be called directly to bypass the guarded solve path. 9. A validation owner independent from the solver owner calls `OptimizationValidate` and recomputes domains, hard constraints, objective, baseline delta, and IIS traceability from raw values. + Only then publish and link the real SolveResult and ValidationReport. Never prepublish guessed results. DeliveryBundle must preserve the exact evidence chain and its human approval status. 10. The user approves only through the platform's dedicated human approval control after the exact linked chain passes review and independent validation. No Agent or specialist may create that approval. -- When training data exists, call `OptimizationPredict`; use ordered holdout, train-only imputation, tuning, metrics, baseline comparison, and explicit fallback rules. +- In step 5's confirmed prediction branch, use `OptimizationPredict` with ordered holdout, train-only imputation, tuning, metrics, baseline comparison, and explicit fallback rules. - Compile general models with `OptimizationCompile`, solve once through guarded `OptimizationSolve`, and retain status, variables, objective, request/job IDs, HTTPS transport, selected-engine evidence, and IIS when infeasible. - Require the validation owner to call `OptimizationValidate` and recompute variable domains, hard constraints, objective, baseline delta, and IIS traceability from raw values. - Treat every settled successful Tool call as authoritative. After an interruption, synthesize the persisted result without repeating the Tool. ## L2 -- Until the fact-confirmation gate passes, clarify only: do not publish modeling artifacts, call a solver, delegate a solver-capable Agent, or fill hidden conditions with defaults, simulations, or industry convention. +- Until the fact-confirmation gate passes, use only the clarification operations above: do not publish modeling artifacts, call a solver, delegate a solver-capable Agent, or fill hidden conditions with defaults, simulations, or industry convention. Ledger labels such as confirmed_user are not substitutes for dedicated platform confirmation receipts. - Interaction mode changes terminology, grouping, per-turn batch size, and example depth only. It never changes fact states, mandatory information, triggered conditions, the modeling-confirmation summary, or the stop gate. The user's explicit choice in the current request overrides historical preference; switching mode preserves confirmed facts and continues with every remaining item. - If the user cannot confirm an item, deliver the gap, model impact, required owner/data, and optional reduced scope. Never interpret an omitted answer as absent, false, zero, or unlimited. - Use the fast path only when the user supplied a complete `OptimizationSpec`. It may omit unnecessary scene, prediction, or data-authoring work, but it must still create/propose the governed DecisionWorkspace representation, obtain every required dedicated human confirmation, bind the current revision, publish and link exact revisions, pass peer review and execution guards, delegate one solve and one independent validation, and wait for dedicated human approval before an entry-owned `DeliveryBundle` is decision-grade. diff --git a/skills/workforce-optimization/SKILL.zh-CN.md b/skills/workforce-optimization/SKILL.zh-CN.md index 2b79fc2..1f758c9 100644 --- a/skills/workforce-optimization/SKILL.zh-CN.md +++ b/skills/workforce-optimization/SKILL.zh-CN.md @@ -14,7 +14,8 @@ - 平台保留个人会话直接调用 `MindOptSolve` 和 compile 临时覆盖参数，只是本技能团队治理流程之外的向后兼容、非 decision-grade 专家路径。不得把未绑定的个人调用描述成已审阅、已由真人确认、可恢复或 decision-grade；团队运行必须使用受保护的 `OptimizationSolve`，并把求解限制写入 committed specification。 - 在承诺或发起真实求解前，必须验证外部 Connector 已配置且 ready、所需 capabilities 可用，并确认该部署具备当前用途所需的有效许可证。仅发现 `MindOptSolve` Tool 名称，不能证明求解器已经安装、授权、可达或完成付费。 - 外部依赖不可用时，必须说明具体缺少的前置条件并在调用求解器前停止。仍可完成需求澄清，并交付供后续执行的 `SceneSpec`、`DataContract` 和 `OptimizationSpec`，但不得伪造 `SolveResult`，也不得宣称可行、最优或收益。 -- 自然语言入口在路由或建模前必须完整读取 `references/requirement-clarification-framework.zh-CN.md`，按业务澄清框架识别真实决策、六场景必问项和条件触发项。 +- 自然语言入口在路由或建模前必须按用户当前对话语言完整读取框架：中文使用 `references/requirement-clarification-framework.zh-CN.md`，英文使用 `references/requirement-clarification-framework.md`，据此识别真实决策、必问项和条件触发项。技能 metadata 默认语言不覆盖用户语言；固定事实门尾注也使用相应语言版本。 +- Skill 激活状态按当前服务进程生命期和父 Agent 活动轮次隔离。应用/服务重启或重试 fork 后，当前入口 Agent 必须先重新加载本技能，再检查隐藏的优化工具或委派阶段 Owner；委派前用 `ToolCatalog` 核实 `TeamArtifact` 及该阶段所需优化工具。子 Agent 自行加载 Skill 不能扩大从尚未激活父 Agent 继承的工具上限。不得持久化激活状态、扩大默认工具、切换来源/scope 绕过上限，也不得在能力缺失时要求子 Agent 伪造工件。 - 先读取当前上下文已注入的 AgentFS 用户画像、偏好和关系记忆，按其中已由用户确认、仍有效且无冲突的专业熟悉度或沟通偏好选择专业、业务引导或证据不足时的自适应表达；岗位名称、公司归属、单次术语使用和模型猜测不是充分证据。 - 专业表达可以一次公开结构化完整信息契约并接受批量回答；业务引导表达用白话按影响顺序分组、允许任意必要轮次；证据不足时先给中性覆盖范围并询问用户偏好。任何表达都必须维护同一完整问题地图，不得以减少轮次、问题数量或认知负担为由跳过模型影响项。 - 每次首轮回复必须以业务澄清框架规定的两句“固定事实门尾注”逐字收尾，不得同义改写、缩短、合并或遗漏任何一句。 @@ -22,25 +23,43 @@ - “今天”“明日”“未来 N 天”“本季度”等业务相对时间，在本轮确认业务时区、业务日历、日期/时刻锚点以及适用的日切、截点、节假日和跨日规则前，一律保持 `pending_confirmation`；系统时钟或宿主机时区只是环境证据，不是业务规则。 - 每个新需求必须隔离历史污染：其他会话、Plan、工件、记忆或样例中的事实一律保持 `pending_confirmation`，只有用户在当前请求中明确沿用后才能转为事实；首轮不得搜索或复用语义相似的旧 Plan 作为证据。 - 用户只与入口 Agent 交互；入口负责路由、集中追问和最终交付，每个阶段只有一个 Owner。 +- “只澄清、暂不求解”仍走本流程。普通 AskUserQuestion 只用于非建模设置选择或已明确说明的能力降级，不能把其答复当成 DecisionWorkspace 答案或真人确认。 +- 使用非专家流程前，检查实时 DecisionWorkspace Schema 是否提供 semantic_checks_version、request_clarification、interpret_clarification、sourceField 和 evidenceLinks，并确认 check_semantics 可用。缺少契约时停留在澄清并说明需要兼容客户端；不得直接编辑 AgentFS 记录模拟缺失门禁，也不得切到个人求解路径绕过。 +- 先只读调用 DecisionWorkspace list 探测；全局 TaskBoard/assistance 能力关闭或不可用时，说明缺少用户处理入口并停留在普通文本澄清，不创建用户无法回答的补问，也不在用户未要求时开启能力。 +- 事实门通过前，澄清操作可以创建 semantic_checks_version=1 的团队工作区、提议业务节点、检查用户明确授权的数据源并记录 request_clarification。这些不是数学建模、发布建模工件、委派求解或调用求解器的授权。 +- 决定性缺口通过 request_clarification 提供可回答的问题、原因、规范类型、单位和有依据的约束。同陈述/约束保持同一逻辑问题，不编造上下界来减少选项。按业务影响组织问题，并用普通语言说明剩余覆盖范围。 +- 平台已提供 unknown 和 raw_text 回答通道；不得把“目前不确定”“不知道”等知识缺口作为精确 choices 或 node.value 的占位值，它们不是业务选项。reason 直接解释原因，不重复界面已有的“为什么问”标签。 +- 当前用户消息已唯一给出完整业务值及必要单位/窗口时，提议节点必须写入类型化 `node.value`，状态保持 proposed 等待专用真人确认；“Agent 提议值”不是“Agent 代替确认”。省略 value 会把已知事实错误降为 needs_input，不得用只有 summary 的节点冒充可确认陈述。只有未知或仍有歧义时才省略 value 并进入补问。 +- 真人提交 value 仍是提议，不是确认。仅在 raw_text 能唯一确定业务值及必要单位/统计窗口时，才用 interpret_clarification 关联原答案与规范化节点，保留原话并等待真人确认。仍有歧义时保留原答案和 needs_input，解释尚缺什么，不调用 interpret_clarification 或填 canonical 占位值。例如“差不多八小时，不知按天还是按周”既不能确定精确上限，也不能确定周期。不得普通 upsert 切断原答案关联、伪造回执或默认补值。 +- 由平台在有效缺口结算后继续原来源会话。不得靠发新消息轮询、换请求身份绕过去重、复活已取消来源或重跑 unknown 派发。pending/解释信号不是求解授权；必须重读精确工作区并遵守全部门禁。 +- 真实数据用已授权 FileResourceRef、bytesHash、精确字段/类型/单位和经确认 timeScope 绑定；按需声明 required/unique/range/enum/foreign_key/cutoff 有限规则。range/enum 常量及 FK 两侧单位必须一致。每个实际消费字段都须用 modelSemantics.sourceField 和 sourced_from 关联业务量，再追踪入模；未使用列不必入模。单位/窗口转换须产生显式转换、可追溯且重新确认的来源，不得只改单位标签。 +- 为确切模型约束提议 blocking validation 正例、反例和临界例，提供完整候选赋值与预期硬/软行为；至少覆盖缺约束、错误统计窗口和意外软化。平台 check_semantics 独立复算已声明用例；求解器结果或第二份 Agent 解释本身不能证明业务正确。 +- 所有新 decision-grade `OptimizationSpec` 必须选择实时 TeamArtifact payload 中 `schema_version` 明确等于 `2` 的分支；legacy v1 只能只读兼容，不能关联为当前决策的批准依据。发布前完整读取 v2 Schema，构造完整 algebraic/CP `model`、`problem_family`、精确 `data_refs` 与 `semantic_contract`。合同必须声明 `solve_intent`，并为模型中实际存在的每个 material objective、variable、constraint 和 data reference 各声明且仅声明一项，写入已确认的 dimension、canonical unit 及适用 time scope；不得缺失、未知、重复，也不得用展示标签、JSON Pointer 或隐式单位替代。请求 `link_artifact` 前重新读取已发布的精确 revision 并核对这个闭合集合；legacy 或语义不完整工件即使编译回执成功，也不是 decision-grade 证据。 +- 同行审核要求返工 completed 工件阶段时，原 Owner 必须重新 claim 同一 canonical Task 与 Work Context，保持旧阶段 completed，并用该 completed source stage 与同一稳定 artifact ID 调用 `TeamArtifact(action="begin_rework")`。只使用平台返回的 rework stage ID 发布同一 artifact 的下一 revision，随后完成 rework stage，并把 Task 提交到新的 review round。不得重开 completed stage、创建普通替代 stage、换新 artifact ID、复用旧审核轮次的 rework stage，或伪造 review/claim/Plan 围栏；`begin_rework` 不可用或被拒绝时必须停止并报告缺少的治理事实，不得继续发布。 +- 在真人确认与工件关联前，`OptimizationSpec.data_refs` 中每个实际数据引用都必须有一个已确认业务来源节点，其 `modelImpact` 明确为 `input`，dimension、canonical unit 及可选 time scope 与 `semantic_contract` 对应元素完全一致。`modelImpact=none` 的数据快照只是展示证据，不能覆盖 material trace；正例、反例和临界例属于确定性语义检查，不得重复加入artifact material bindings。 +- 已确认业务变化推进 model-input hash 后，必须先在该精确 binding 下刷新所有被消费的父工件，再发布子工件；不得把fresh OptimizationSpec与stale SceneSpec/DataContract父链拼接。中断/失败后对同一source stage与artifact再次调用`begin_rework`；平台只会在旧Run不再running、同一review event/Task/Work Context/Plan仍权威、新claim严格更大且尚无新artifact revision提交时续接既有stage。只能使用平台返回的stage回执，不能另造第二stage逃避stale或partial chain。 +- 文件证据用 evidenceLinks 显式关联同节点 evidenceRefs，只使用已授权 FileResourceRef，不猜路径或任意 URL。解释失败时给出原因码、精确字段/模型元素、冻结预期、实际观察、影响和安全下一步；引导用户使用图中的问题/来源/模型入口和变更影响预览。分支颜色、查看证据或预览都不是执行授权。 - 事实确认门通过后，必须严格按以下治理顺序执行，不得跳过或调换控制点： 1. 入口 Agent 在构造写入前，按需读取 `DecisionWorkspace(action="schema")` 的对应 section，以及每类 `TeamArtifact(action="schema")` 契约。 2. 入口 Agent 创建团队 DecisionWorkspace，或用 CAS 提交业务语言提议；提议绝不得伪造真人回执。 3. 用户只能通过平台专用真人控件确认或驳回阻断事实；驳回项保留为可审计的非活跃 tombstone。所有 Agent 必须等待权威结果。 4. 只有顶层入口 Agent 可以对已验证的当前 workspace revision 与 model-input hash 调用 `DecisionWorkspace(action="bind_workspace")`；Specialist 不得绑定、替换或绕过。 - 5. 指定阶段 Owner 按依赖顺序通过 `TeamArtifact` 发布 `SceneSpec`、`DataContract`、可选 `PredictionArtifact`、`OptimizationSpec`、`SolveResult`、`ValidationReport` 和 `DeliveryBundle`，并保留返回的精确 artifact revision 与 DecisionWorkspace snapshot。 + 5. 指定阶段 Owner 按依赖顺序通过 `TeamArtifact` 发布 `SceneSpec`、`DataContract`、可选 `PredictionArtifact` 和带上述完整 `semantic_contract` 的 decision-grade OptimizationSpec v2，保留精确 artifact revision 与 DecisionWorkspace snapshot。经确认的预测输入需要训练数据时，在本步骤内调用 OptimizationPredict、发布真实 PredictionArtifact，并确认影响模型的预测输出后再创建 OptimizationSpec；无预测输入则省略该分支，不在语义检查之后才补预测。首次模型发布使用平台内部纯编译校验；不得提前调用受保护 OptimizationCompile 来绕开模型发布与语义检查的依赖。 6. 入口 Agent 使用精确 artifact ID、精确 revision 和语义绑定调用 `DecisionWorkspace(action="link_artifact")`；受治理证据禁止解析到可变 `latest`。 7. 将已链接 revision 提交同伴审阅；独立 reviewer 在执行前检查业务到模型覆盖、单位、变量族、可行性逻辑、来源证据、缺口以及 stale/rejected 排除。 + 用户确认精确来源/规则/用例后，对当前 revision/hash 调用 DecisionWorkspace(action="check_semantics")，检查完整有界报告。缺数据、未知 evaluator、超预算或未确认用例均是阻断，不是通过。审计-only revision 变化不机械重绑；业务语义不变时保持原 model-input snapshot。 8. 依次调用 `OptimizationCompile` 和 `OptimizationSolve`；两者产生副作用前都必须通过平台 DecisionWorkspace execution guard。`MindOptSolve` 只保留兼容 Connector 名称，不得被直接调用来绕过受保护求解路径。 9. 与求解 Owner 不同的验证 Owner 调用 `OptimizationValidate`，基于原始变量独立重算变量域、硬约束、目标值、基线差和 IIS 可追溯性。 + 此后才发布并关联真实 SolveResult 和 ValidationReport，不得提前发布猜测结果。DeliveryBundle 必须保留精确证据链及其真人批准状态。 10. 精确链接链通过审阅和独立验收后，用户只能通过平台专用真人批准控件批准；任何 Agent 或 Specialist 都不得生成该批准。 -- 有训练数据时必须调用 `OptimizationPredict`，执行有序留出、仅训练集插补、调参、指标、基线比较和明确降级规则。 +- 第 5 步已确认的预测分支使用 `OptimizationPredict`，执行有序留出、仅训练集插补、调参、指标、基线比较和明确降级规则。 - 通用模型先用 `OptimizationCompile` 严格编译，再通过受保护的 `OptimizationSolve` 求解一次；保留真实 status、原始变量、objective、request/job ID、HTTPS transport、所选引擎证据和不可行时的 IIS。 - 验证 Owner 必须调用 `OptimizationValidate`，基于原始变量独立重算变量域、硬约束、目标值、基线差和 IIS 可追溯性。 - 已结算且成功的 Tool 调用是权威事实；系统中断后只能综合持久化结果，不得重复执行 Tool。 ## L2 -- 事实确认门未通过时只允许反向追问：不得发布建模工件、调用求解器、委派 solver-capable Agent，或用默认值、模拟情况、行业惯例补全隐形条件。 +- 事实确认门未通过时只允许上述澄清操作：不得发布建模工件、调用求解器、委派 solver-capable Agent，或用默认值、模拟情况、行业惯例补全隐形条件。confirmed_user 等事实台账标签不能代替平台专用真人确认回执。 - 交互模式只改变术语、分组、单轮批量和举例深度；不得改变事实状态、必问信息集合、条件触发项、建模确认摘要或停止门。用户本轮显式选择优先于历史偏好，切换模式时保留已确认事实并继续补齐其余项目。 - 用户无法确认时交付待确认项、模型影响、所需责任方/数据和可选降级范围；不得把未回答解释为不存在、否、零或不限制。 - 只有用户已经提供完整 `OptimizationSpec` 时才走快速路径。快速路径可以省略不必要的场景、预测或数据编写，但仍必须创建/提议受治理的 DecisionWorkspace 表达、取得所有必要的专用真人确认、绑定当前 revision、发布并链接精确 revision、通过同伴审阅和 execution guard、执行一次求解委派和一次独立验证，并等待专用真人批准后，入口发布的 `DeliveryBundle` 才能成为 decision-grade 交付。 diff --git a/skills/workforce-optimization/catalog-metadata.v1.json b/skills/workforce-optimization/catalog-metadata.v1.json index 9e4b234..8b3724e 100644 --- a/skills/workforce-optimization/catalog-metadata.v1.json +++ b/skills/workforce-optimization/catalog-metadata.v1.json @@ -11,12 +11,12 @@ "zh-CN": { "name": "人效与资源优化", "summary": "用决策工作区共管人效建模、受保护求解与独立验收；MindOpt 需外部授权部署", - "description": "当用户自然提出服务范围、分层资源分配、绩效目标、集中任务调度、人员配置、排班或通用 LP/MILP 需求时，通过 DecisionWorkspace 的人机确认、精确版本制品、入口 Agent 绑定、同伴审阅、执行门禁、独立验收和真人批准形成可恢复治理链。选择 MindOpt 引擎时，实际求解仍依赖使用方另行取得适用许可证、部署并接入 MindOpt；客户端和本技能不包含求解器软件、许可证、算力托管或相关费用。" + "description": "用户提出排班、工时上限、人员配置、服务覆盖、资源分配、绩效目标、任务调度或 LP/MILP，即使“只澄清、暂不求解”，也先用 Skill 工具加载本技能。影响模型的事实使用 DecisionWorkspace 补问及真人确认卡，不能用普通 AskUserQuestion 代替。澄清无需连接求解器；实际 MindOpt 求解需使用方另行取得适用许可证、部署并配置连接，软件、许可证、算力托管及费用均不包含在技能中。" }, "en-US": { "name": "Workforce and Resource Optimization", "summary": "Co-manage workforce models, guarded solving, and independent validation; MindOpt is externally licensed", - "description": "When users naturally request service coverage, hierarchical resource allocation, performance targets, centralized task scheduling, staffing, shift planning, or general LP/MILP, use DecisionWorkspace human confirmation, exact-version artifacts, entry Agent binding, peer review, execution guards, independent validation, and human approval to create a recoverable governance chain. When MindOpt is selected, actual solving still requires the user to obtain an applicable license, deploy MindOpt, and configure its connector; the client and this Skill do not include the solver, license, hosted compute, or related fees." + "description": "Load this Skill for the first clarification of staffing, shifts, work-hour limits, service coverage, resource allocation, targets, task scheduling or LP/MILP, including clarify only / do not solve yet requests. Use DecisionWorkspace question and human-confirmation cards for model-changing facts; generic AskUserQuestion is not a substitute. Clarification needs no connected solver. Actual MindOpt solving requires a separately licensed/deployed solver and configured connector; software, licenses, hosting and fees are not included." } }, "category": "business", @@ -29,14 +29,14 @@ }, "release": { "state": "known", - "version": "2.3.4", + "version": "2.9.0", "versionScheme": "semver" }, "timestamps": { "catalogUpdatedAt": { "state": "known", - "value": "2026-08-29T14:48:56Z", - "precision": "second" + "value": "2026-09-01", + "precision": "day" }, "releasePublishedAt": { "state": "unknown" diff --git a/skills/workforce-optimization/references/requirement-clarification-framework.md b/skills/workforce-optimization/references/requirement-clarification-framework.md index 3d2d01e..461ac68 100644 --- a/skills/workforce-optimization/references/requirement-clarification-framework.md +++ b/skills/workforce-optimization/references/requirement-clarification-framework.md @@ -17,6 +17,8 @@ Maintain `fact_state`, `value`, `source`, and `model_impact` for every modeling Mandatory rules: +The ledger states describe evidence for discussion, not authorization receipts. In the governed DecisionWorkspace, model-changing statements still require dedicated human confirmation. Before that gate, schema discovery, business-node proposals, authorized data inspection and request_clarification are permitted clarification actions; mathematical modeling/artifact publication/solver delegation remain prohibited. Use interpret_clarification only when raw_text uniquely determines the business value and required unit/window, then obtain explicit confirmation. Ambiguous raw_text stays needs_input with its original receipt; explain the gap without inventing a normalized value. Unknown uses the platform's unknown channel, not an epistemic placeholder in exact choices or node.value. Conversation text, this ledger and Agent-owned files cannot manufacture platform human facts. + 1. Never interpret a missing answer as absent, false, zero, unlimited, or industry standard. 2. Never replace confirmation with a reasonable default or a simulated possible situation. 3. If a factor has two or more model-changing values, mark it `pending_confirmation` and ask. diff --git a/skills/workforce-optimization/references/requirement-clarification-framework.zh-CN.md b/skills/workforce-optimization/references/requirement-clarification-framework.zh-CN.md index 0054cfa..f4c8df6 100644 --- a/skills/workforce-optimization/references/requirement-clarification-framework.zh-CN.md +++ b/skills/workforce-optimization/references/requirement-clarification-framework.zh-CN.md @@ -17,6 +17,8 @@ 强制规则： +台账状态只表达供讨论的来源证据，不是授权回执。在受治理 DecisionWorkspace 中，影响模型的陈述仍须通过平台专用真人确认。事实门之前可发现 Schema、提议业务节点、检查已授权数据和提交 request_clarification，但仍不得数学建模、发布建模工件或委派求解。仅当 raw_text 唯一确定业务值和必要单位/窗口时才用 interpret_clarification 提议规范化陈述并取得确认；有歧义的原话保留原回执和 needs_input，只解释缺口，不编造规范化值。unknown 使用平台专用通道，不作为精确 choices 或 node.value 的知识缺口占位值。聊天文本、台账及 Agent 自写文件不能制造平台真人事实。 + 1. 不得把未回答解释为“不存在”“否”“0”“不限制”或“按行业惯例”。 2. 不得以“合理默认”“先模拟一个可能情况”替代用户确认；示例数值只能标记为 `hypothesis_not_modelable`。 3. 同一因素若存在两种及以上会改变模型的可能值，必须标记 `pending_confirmation` 并追问。