mirror of
https://github.com/iflytek/skillhub.git
synced 2026-11-14 09:01:16 +00:00
docs(site): center diagrams and separate avatar governance from deployment
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
This commit is contained in:
XiaoSeS
parent
aa764dc8b0
commit
f944b718d7
17 changed files with 421 additions and 280 deletions
|
|
@ -62,6 +62,7 @@ export default defineConfig({
|
|||
{ text: '管理命名空间', link: '/guide/namespace' },
|
||||
{ text: '审核技能与套装', link: '/guide/review' },
|
||||
{ text: '安全扫描与报告', link: '/guide/scanner' },
|
||||
{ text: '技能头像与审核', link: '/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
@ -71,7 +72,7 @@ export default defineConfig({
|
|||
{ text: 'Docker 部署', link: '/guide/deployment' },
|
||||
{ text: 'Kubernetes 部署', link: '/guide/kubernetes' },
|
||||
{ text: '前端动作统计', link: '/guide/frontend-analytics' },
|
||||
{ text: '技能头像与审核', link: '/guide/skill-avatars' },
|
||||
{ text: '配置头像机器审核服务', link: '/guide/avatar-moderation-configuration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
@ -137,6 +138,7 @@ export default defineConfig({
|
|||
{ text: 'Manage namespaces', link: '/en/guide/namespace' },
|
||||
{ text: 'Review submissions', link: '/en/guide/review' },
|
||||
{ text: 'Configure scanning', link: '/en/guide/scanner' },
|
||||
{ text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
@ -146,7 +148,7 @@ export default defineConfig({
|
|||
{ text: 'Deploy with Docker', link: '/en/guide/deployment' },
|
||||
{ text: 'Deploy on Kubernetes', link: '/en/guide/kubernetes' },
|
||||
{ text: 'Frontend analytics', link: '/en/guide/frontend-analytics' },
|
||||
{ text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' },
|
||||
{ text: 'Configure avatar machine moderation', link: '/en/guide/avatar-moderation-configuration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
4
docs/skillhub/.vitepress/theme/index.ts
Normal file
4
docs/skillhub/.vitepress/theme/index.ts
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
import DefaultTheme from 'vitepress/theme'
|
||||
import './style.css'
|
||||
|
||||
export default DefaultTheme
|
||||
3
docs/skillhub/.vitepress/theme/style.css
Normal file
3
docs/skillhub/.vitepress/theme/style.css
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
.vp-doc img[src*='/diagrams/'] {
|
||||
margin-inline: auto;
|
||||
}
|
||||
|
|
@ -272,7 +272,9 @@ Check the following in order:
|
|||
|
||||
## Q: How does an account created through OAuth (GitHub / GitLab, etc.) get admin rights?
|
||||
|
||||
A: The first OAuth login creates a regular user. An existing `SUPER_ADMIN` (for example the bootstrap admin created during initialization) has to promote it from the admin console.
|
||||
A: External sign-in first follows the existing admission policy. A newly created external account with status `ACTIVE` can receive a configured platform role when the provider supplies a verified email and an enabled initial-role rule matches it. Without a matching rule, no platform-management role is granted automatically. Rules apply only during new-account creation; they do not update existing accounts or merge accounts with the same email. Existing accounts use user management with the required platform permissions; only a super administrator (`SUPER_ADMIN`) may grant that role.
|
||||
|
||||
See [Accounts and access tokens](./guide/account-access.html), the [initial-role service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/settings/InitialExternalRoleGrantService.java), and the [account creation flow](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/identity/IdentityBindingService.java).
|
||||
|
||||
A `USER_ADMIN` can manage user status and assign platform roles other than `SUPER_ADMIN`, but cannot grant `SUPER_ADMIN` to any account or change the role of an existing `SUPER_ADMIN`. Only a `SUPER_ADMIN` can perform those two operations.
|
||||
|
||||
|
|
|
|||
111
docs/skillhub/en/guide/avatar-moderation-configuration.md
Normal file
111
docs/skillhub/en/guide/avatar-moderation-configuration.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# Configure avatar machine moderation
|
||||
|
||||
This page is for deployment operators. It covers service activation, credential injection, service updates, and actual-call verification for avatar moderation. A running registry and an image containing this feature are prerequisites. It does not deploy a separate moderation engine or explain owner uploads. Submission, policy, and review entry points are covered by [Skill avatars and moderation](./skill-avatars.html).
|
||||
|
||||
## Prerequisites and responsibilities
|
||||
|
||||
| Operation | Responsible actor | Prerequisite and completion criterion |
|
||||
| --- | --- | --- |
|
||||
| Inject credentials and update containers | Operator with deployment permission | A running registry and access to its deployment/private configuration; update the original project service |
|
||||
| Enable moderation policy | Super administrator (`SUPER_ADMIN`) | Save switches after configuration is present; saving does not prove actual cloud calls |
|
||||
| Create an acceptance candidate | Skill owner | Submit a new avatar to a non-private test skill; old applications do not prove the new setup |
|
||||
| Check review and public outcomes | Authorized skill reviewer | Compare the candidate and machine result in the existing skill application; prohibited content must not be approved for testing |
|
||||
|
||||
## Select a provider and confirm permissions
|
||||
|
||||
|
||||
Select one startup provider: `xfyun` or `aliyun`. Runtime switches cannot change providers. Credentials are unnecessary while machine moderation is disabled. Real calls can incur provider charges; account availability and quotas must be checked by the deployment operator.
|
||||
|
||||
| Provider | Service | Credentials |
|
||||
| --- | --- | --- |
|
||||
| Xfyun | Image moderation | APPID, APIKey and APISecret |
|
||||
| Aliyun | Enhanced content security, Shanghai `profilePhotoCheck` | RAM AccessKey ID and AccessKey Secret |
|
||||
|
||||
For Xfyun, APIKey maps to `access-key-id` and APISecret to `access-key-secret`; see the [provider API (Chinese)](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html). For Aliyun, consult [service onboarding (Chinese)](https://help.aliyun.com/zh/document_detail/467828.html) and grant the required `yundun-greenweb:DescribeUploadToken` and `yundun-greenweb:ImageModeration` permissions rather than full access to the deployment’s OSS buckets.
|
||||
|
||||
Aliyun uses temporary upload credentials and synchronous moderation; no dedicated user-managed moderation bucket is required. This is independent of SkillHub's package/avatar storage. The adapter maps `none/low` risk to pass and `medium/high` to block; unknown, empty or failed responses do not pass. Human handling of a blocked result follows the avatar moderation policy; it is not a final human decision by the provider.
|
||||
|
||||
## Inject private configuration and recreate the service
|
||||
|
||||
First configure the normal release stack. Create a private directory outside the repository and replace `/etc/skillhub/private` with its actual path. The following filesystem permissions are this page's example, not application defaults. Credential files must not be committed to Git.
|
||||
|
||||
| Object | Example permissions | Effect and boundary |
|
||||
| --- | --- | --- |
|
||||
| Private directory | `700` | Set by the deployment operator; only its owner may access it |
|
||||
| Credential and override files | `600` | Set by the deployment operator; only their owner may read or write them |
|
||||
|
||||
Standard Compose only passes declared settings; adding arbitrary values to `.env.release` does not inject them into the server.
|
||||
|
||||
Create `avatar-moderation.env` with **one** provider configuration. Replace placeholders and keep `SPRING_APPLICATION_JSON` as valid single-line JSON:
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}}
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}}
|
||||
```
|
||||
|
||||
If the deployment already uses `SPRING_APPLICATION_JSON`, merge this subtree into it; do not replace other configuration or define duplicate variables. An override's `environment` takes precedence over `env_file`. Escape credential characters correctly for JSON.
|
||||
|
||||
Create `compose.avatar.yml` in the same private directory:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
server:
|
||||
env_file:
|
||||
- /etc/skillhub/private/avatar-moderation.env
|
||||
```
|
||||
|
||||
From the repository root, retain the deployment’s existing project name, Compose files and other options, then append the override:
|
||||
|
||||
```bash
|
||||
make validate-release-config
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
up -d --no-deps server
|
||||
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
ps server
|
||||
```
|
||||
|
||||
This updates an existing full stack. For initial deployment, use `up -d` instead of `up -d --no-deps server`. A restart does not reload changed container environments; recreate the service and preserve the override in future updates. Other platforms should inject the same `skillhub.avatar.moderation` properties through their secret mechanism.
|
||||
|
||||
::: warning Xfyun outbound logging
|
||||
The Xfyun interface carries `accessKeySecret` in URL parameters. The adapter avoids logging complete URLs and raw exceptions. Also disable HTTP debug logging and prevent proxies, tracing and external log collectors from capturing that request URL. Never share rendered secret-bearing Compose configuration or container environments.
|
||||
:::
|
||||
|
||||
## Enable moderation and verify actual results
|
||||
|
||||
1. After server health checks pass, open System Configuration as a super administrator.
|
||||
2. Enable machine moderation; retaining manual review initially makes decisions observable.
|
||||
3. As a skill owner, submit a **new** avatar for a non-PRIVATE test skill.
|
||||
4. Inspect the machine result on the update page. If manual review is enabled, review its image and result in the skill review queue.
|
||||
5. Verify pass, block and error handling: the old public image remains until approval, blocked/error candidates stay private, and manual rejection has a visible reason. Do not approve prohibited content merely for testing.
|
||||
|
||||
Saving credentials or enabling a switch checks configuration completeness, not real account permissions, connectivity, quota or responses. Existing candidates are not automatically rescanned after enabling a switch. Code and simulated tests do not replace acceptance with the deployment account; verify connectivity, result mapping and failure handling after setup or credential rotation.
|
||||
|
||||
## Change providers and handle existing applications
|
||||
|
||||
Each application retains snapshots of its machine/manual switches and provider. Later configuration does not rewrite applications or rerun completed results. Before switching, authorized reviewers should handle pending applications. Update private configuration and recreate `server`, then submit a new candidate as its skill owner to use the new provider.
|
||||
|
||||
An old candidate still requiring its original provider returns `ERROR` after a provider switch; it does not silently use the new provider. Changing only an administration switch does not recover that task. Candidate retention is defined in [Skill avatars and moderation](./skill-avatars.html); provider-side temporary uploads follow external service rules and are a separate lifecycle.
|
||||
|
||||
## Completion criteria and troubleshooting
|
||||
|
||||
Enabling machine moderation only confirms that the selected provider's required configuration is present. Verify integration through actual results and candidate visibility on a new application. Health, supplied credentials, and saved switches do not replace actual-call acceptance.
|
||||
|
||||
| Symptom | Likely cause | Diagnostic action | Resolution |
|
||||
| --- | --- | --- | --- |
|
||||
| Provider unavailable when enabling | Invalid `provider` or missing injected credentials | Compare private property names and whether the startup command used the same override | Correct configuration and recreate the original service; do not print full environments or Secrets |
|
||||
| Behavior unchanged after configuration edits | Container was only restarted or another value overrides the setting | Compare Compose file order and `environment`/`env_file` definitions | Merge the JSON and recreate the service; do not overwrite unrelated Spring settings |
|
||||
| A new application's machine state is `ERROR` | Service activation, permissions, quota, or outbound network failure | Inspect its machine state and provider account settings; Aliyun also requires its temporary OSS upload endpoint | Restore dependencies before retrying under cooldown rules; do not interpret errors as passes |
|
||||
| Old candidates fail after switching | The saved provider differs from the active deployment | Compare the candidate provider with the current `provider` | Handle the old application or resubmit; do not directly edit candidate snapshots |
|
||||
| Existing applications have no new result after enabling | Switch changes do not rescan old applications | Check candidate time and machine state on the update page | Verify through a new application; do not repeatedly approve old applications to trigger calls |
|
||||
|
||||
Configuration sources: [Provider gateway](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AvatarModerationGateway.java), [Xfyun adapter](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/XfyunAvatarModerationProvider.java), and [Aliyun adapter](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AliyunAvatarModerationProvider.java). Commands use [release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml). Other deployment paths must inject equivalent properties through their Secret mechanism rather than copying Compose update commands.
|
||||
|
|
@ -481,13 +481,10 @@ skillhub remove pdf-parser --json
|
|||
skillhub doctor --json
|
||||
```
|
||||
|
||||
Success response format:
|
||||
The following JSON excerpt shows only the success flag, not a complete command response. Result fields depend on the command:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
...
|
||||
}
|
||||
{"ok": true}
|
||||
```
|
||||
|
||||
Error response format:
|
||||
|
|
@ -719,17 +716,13 @@ skillhub search test --registry https://skillhub.example.com
|
|||
|
||||
### Installation Directory Conflict
|
||||
|
||||
```bash
|
||||
# Reinstall only when the existing directory has matching SkillHub source metadata
|
||||
skillhub install pdf-parser --force
|
||||
Check the active registry, target Agent, installation directory, source metadata, and local changes before replacing files. The following example targets Codex; use the actual Agent identifier for other targets.
|
||||
|
||||
# Or remove first then install
|
||||
skillhub remove pdf-parser
|
||||
skillhub install pdf-parser
|
||||
```bash
|
||||
skillhub list --agent codex --json
|
||||
```
|
||||
|
||||
`--force` never overwrites an unmanaged directory or a Skill installed from another registry,
|
||||
namespace, or slug. Move or explicitly remove that directory first.
|
||||
Compare `installDir` with the conflicting path and read that directory's `SKILL.md`. Use `--force` only after confirming the same installation source, making a backup, and explicitly accepting the loss of local changes. The option does not take over unmanaged, different-source, or disabled targets. If provenance is uncertain, choose another directory or scope; do not delete files or inventory records as a diagnostic step.
|
||||
|
||||
### Corrupted Inventory
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,17 @@
|
|||
# Documentation map
|
||||
|
||||
Choose the task you want to complete. Start with [Quick Start](../quickstart.html) to install your first skill; deployment and development guides are not prerequisites.
|
||||
Select the required task. [Quick Start](../quickstart.html) covers the first installation; deployment and development guides are not prerequisites.
|
||||
|
||||
## Start
|
||||
|
||||
- [Accounts and access tokens](./account-access.html): web sign-in, CLI authorization, token expiry, and password reset.
|
||||
- [Introduction](../introduction.html): understand the registry's purpose.
|
||||
- [Quick start](../quickstart.html): find, install, and use a skill in your Agent.
|
||||
- [Quick start](../quickstart.html): find, install, and use a skill in the target Agent.
|
||||
- [FAQ](../faq.html): troubleshoot login, installation, and configuration.
|
||||
|
||||
## Use skills
|
||||
|
||||
| Your task | Read |
|
||||
| Task | Read |
|
||||
| --- | --- |
|
||||
| Find a skill and inspect its versions and visibility | [Find and install skills](./skill-discovery.html) |
|
||||
| Install pinned members together and start with their entry skill | [Manage skill suites](./skill-suites.html) |
|
||||
|
|
@ -30,15 +30,16 @@ Prepare `SKILL.md` and its supporting files, then submit. An accepted submission
|
|||
- [Manage namespaces](./namespace.html): members, roles, and resource visibility.
|
||||
- [Review submissions](./review.html): handle Skill and Suite applications.
|
||||
- [Configure scanning](./scanner.html): connect the scanning service and interpret results.
|
||||
- [Skill avatars and moderation](./skill-avatars.html): skill-owner submissions, authorized review, and moderation policy managed by super administrators.
|
||||
|
||||
## Deploy and operate
|
||||
|
||||
Read these guides when you need to run your own registry. Choose a deployment method before configuring optional integrations.
|
||||
These guides apply to self-hosted registry operation. Select a deployment method before configuring optional integrations.
|
||||
|
||||
- [Deploy with Docker](./deployment.html): installation, configuration, upgrades, and backups.
|
||||
- [Kubernetes deployment (Kustomize / Helm)](./kubernetes.html): choose either the manifest path or the separate Chart path.
|
||||
- [Frontend analytics](./frontend-analytics.html): optional configuration-based integration, consent, and failure checks; match the guide to the deployed version.
|
||||
- [Skill avatars and moderation](./skill-avatars.html): administrator configuration for image moderation providers.
|
||||
- [Configure avatar machine moderation](./avatar-moderation-configuration.html): provider selection, private credentials, service updates, and actual-call acceptance for deployment operators.
|
||||
|
||||
## Develop and integrate
|
||||
|
||||
|
|
|
|||
|
|
@ -1,123 +1,80 @@
|
|||
# Skill Avatars: Uploads, Review, and Provider Configuration
|
||||
# Skill avatars and moderation
|
||||
|
||||
This guide covers skill avatars, not account profile pictures. Image moderation is separate from skill-package security scanning.
|
||||
This page explains avatar submission by skill owners and application handling by authorized reviewers. Skill avatars do not include account profile pictures. Image moderation and skill-package security scanning are independent checks. Deployment operators configure services, credentials, and containers through [Configure avatar machine moderation](./avatar-moderation-configuration.html).
|
||||
|
||||
## Upload or replace an avatar
|
||||
## Prerequisites and responsibilities
|
||||
|
||||
1. On the publishing page, select a PNG/JPEG; for an existing skill, open its update page from My Skills. An avatar-only change does not require a new skill version.
|
||||
2. Adjust the square crop and zoom, then wait for upload success. Pending or failed uploads prevent submission. Without an avatar, the skill uses its initial letter.
|
||||
3. Submit, then inspect the submitted image and review state in My Skills or the update page. Public readers continue seeing the previous approved image until approval.
|
||||
4. If rejected, read the reason, change the image and resubmit. A newer candidate replaces an older pending candidate; old review results cannot overwrite the new image.
|
||||
Sign in to the same registry and identify the target skill and account. Skill ownership controls image maintenance; namespace or platform roles do not automatically permit uploading on another owner's behalf.
|
||||
|
||||
Input must be PNG/JPEG, at most 2 MB, square and no more than 1024 pixels per side. The server validates and re-encodes it as PNG. Upload success means private storage succeeded, not that moderation passed. Temporary upload references expire after 24 hours; upload again if expired.
|
||||
|
||||
Updates retain the existing image unless removal is selected. Avatar-only removal takes effect after a successful submission; removal submitted with a package waits for the associated approval. Cancelling or failing submission leaves the previous image unchanged. There is no separate avatar-management page.
|
||||
|
||||
## Review behavior
|
||||
|
||||
An avatar submitted with a package shares its skill review: the reviewer approves or rejects both. Avatar-only changes requiring manual review enter the same queue as avatar changes and do not create a skill version. Namespace administrators review their namespace; platform skill administrators and super administrators can review namespace and global skills. Existing self-review rules apply. Administrators may remove an avatar but cannot upload one on behalf of its owner.
|
||||
|
||||
Super administrators configure machine and manual moderation in System Configuration (`/dashboard/admin/system-config`). Machine moderation defaults off and manual moderation on. The page manages switches, not provider credentials.
|
||||
|
||||
| Machine | Manual | Avatar-only changes to non-PRIVATE skills |
|
||||
| Operation | Responsible actor | Entry point and boundary |
|
||||
| --- | --- | --- |
|
||||
| Off | Off | Becomes active on successful submission |
|
||||
| Off | On | Waits for manual approval |
|
||||
| On | Off | Becomes active after a machine pass; blocked/error candidates remain private |
|
||||
| On | On | Machine moderation followed by a manual decision |
|
||||
| Add, replace, or remove an avatar | Skill owner | Publishing page or My Skills → Update; avatar-only updates do not create versions |
|
||||
| Review an avatar application | Account with review permission in the target namespace | Existing skill review queue; package and avatar changes submitted together receive a joint decision |
|
||||
| Change machine and manual switches | Super administrator (`SUPER_ADMIN`) | `/dashboard/admin/system-config`; credentials and provider selection are not configured here |
|
||||
| Integrate or switch a provider | Operator with deployment permission | Select a provider and inject private credentials through deployment configuration |
|
||||
|
||||
PRIVATE avatars are owner-readable and used directly without these reviews. Expanding visibility requires review for the target audience. Avatars submitted with packages must wait for the original package review regardless of avatar switches.
|
||||
Team namespace Owners and Admins review their namespace; platform skill administrators (`SKILL_ADMIN`) and super administrators can review team and global skills. [Skill review rules](./review.html) govern self-review; platform roles must not be interpreted as unrestricted self-review permission. Authorized operators may remove an avatar but cannot upload one for its owner.
|
||||
|
||||
| Machine result | Effect |
|
||||
| --- | --- |
|
||||
| `PASSED` | Wait for manual review if enabled; otherwise activate the avatar-only candidate |
|
||||
| `BLOCKED` | Keep the candidate private and retain the old image. Manual reviewers may reject it; overriding a false positive requires an explicit reason. Without manual moderation, the owner can request manual review |
|
||||
| `ERROR` | Keep the candidate private; approval is blocked until the error is resolved and moderation retried |
|
||||
## Submit and update an avatar
|
||||
|
||||
A machine block is neither an upload failure nor a final human rejection. Owners can inspect rejected images and reasons. Automatic retries have a one-hour cooldown and a maximum of three calls including the first. After exhaustion, wait for the cooldown and explicitly retry or resubmit.
|
||||
1. Select a custom PNG/JPEG in the publishing or update form, then adjust the square crop and zoom. Submissions without an image use the skill's initial letter.
|
||||
2. Confirm the crop and wait for upload completion. Pending or failed uploads prevent submission. The server validates the image and re-encodes it as PNG. A successful upload means private storage succeeded, not that moderation approved it.
|
||||
3. After submission, inspect the candidate image and its machine/manual states in My Skills or the update page. Until activation, public detail and lists retain the previous avatar or initial letter; that does not indicate a lost submission.
|
||||
4. After rejection, read the reason, revise the image, and resubmit. A new application supersedes the previous pending candidate; old review results cannot overwrite it. Application records remain available.
|
||||
|
||||
Updates retain the existing image by default. Avatar-only removal restores the initial letter after successful submission; removal submitted with a package waits for that application's approval. Cancelling or failing submission leaves the active image unchanged. There is no separate avatar-management entry point.
|
||||
|
||||
## Moderation policy and application relationship
|
||||
|
||||
An avatar submitted with a package shares one skill application and receives a joint approval or rejection in the existing review detail. It does not activate early. An avatar-only change requiring a human decision enters the same queue, marked as an avatar change, without creating a skill version.
|
||||
|
||||
Super administrators manage two switches in System Configuration. Machine moderation defaults off; manual moderation defaults on. Provider credentials are not configured or displayed there. The following matrix applies to avatar-only changes for non-private skills.
|
||||
|
||||
| Machine | Manual | Activation condition |
|
||||
| --- | --- | --- |
|
||||
| Off | Off | Successful submission |
|
||||
| Off | On | Manual approval |
|
||||
| On | Off | Machine pass; blocked or error results do not activate |
|
||||
| On | On | Machine processing followed by a manual decision |
|
||||
|
||||
PRIVATE avatars are owner-readable and used directly without these checks. Expanding visibility requires moderation for the target audience. An avatar submitted with a package waits for the original skill application's approval regardless of avatar switches.
|
||||
|
||||
## Machine results and human decisions
|
||||
|
||||
| Machine result | Candidate and public image | Next action |
|
||||
| --- | --- | --- |
|
||||
| `PASSED` | Waits for manual review when enabled; otherwise activates an avatar-only candidate | Reviewers verify the candidate and target application; a pass does not prove content effectiveness |
|
||||
| `BLOCKED` | Candidate remains private; the old image remains active | Manual reviewers may reject it; a false-positive override requires an explicit reason. Without manual moderation, the owner may request human review |
|
||||
| `ERROR` | Candidate remains private and cannot be directly approved | Deployment operators resolve configuration, network, or service failures before retrying |
|
||||
|
||||
A machine block is neither an upload failure nor a final human rejection. Owners can inspect rejected candidates and reasons. After manual approval, verify the active image rather than relying only on task text.
|
||||
|
||||
## Input, retry, and retention rules
|
||||
|
||||
| Item | Fixed value or range | Effect and limitation |
|
||||
| --- | --- | --- |
|
||||
| Uploaded image | PNG/JPEG; at most 2MiB; square, at most 1024 pixels per side | Server validation and re-encoding run on upload; out-of-range submissions are rejected |
|
||||
| Temporary upload reference | 24 hours | Expiry requires another upload; this is not the submitted candidate's retention period |
|
||||
| Machine-error cooldown | 1 hour | Wait after an error; repeated requests do not bypass the cooldown |
|
||||
| Automatic calls | 3 total per candidate, including the first | After exhaustion, explicitly retry after cooldown or resubmit |
|
||||
| Discarded candidate images | Private retention for 30 days after rejection, replacement, or removal | Cleanup removes expired images while textual records remain; deletion is not promised at the exact expiry instant |
|
||||
|
||||
Applications retain snapshots of their machine/manual switches and provider. Later switch changes do not rewrite them, and completed machine results are not automatically rerun. If an old candidate still requires its original provider after a switch, processing may return `ERROR`; deployment operators and reviewers must coordinate its handling or use a new application.
|
||||
|
||||
Sources: [Upload references](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarUploadService.java), [image validation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarImageProcessor.java), [candidate states](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java), and [avatar workflow](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarAppService.java).
|
||||
|
||||
## Configure a machine-moderation provider
|
||||
|
||||
Select one startup provider: `xfyun` or `aliyun`. Runtime switches cannot change providers. Credentials are unnecessary while machine moderation is disabled. Real calls can incur provider charges; account availability and quotas must be checked by the deployment operator.
|
||||
Each deployment selects one provider and reads credentials at service startup. The administration page only controls moderation switches; saving a switch does not validate cloud permissions, connectivity, or quota. Deployment operators follow [Configure avatar machine moderation](./avatar-moderation-configuration.html) for integration, rotation, and provider changes, then verify actual calls with a new application.
|
||||
|
||||
| Provider | Service | Credentials |
|
||||
| --- | --- | --- |
|
||||
| Xfyun | Image moderation | APPID, APIKey and APISecret |
|
||||
| Aliyun | Enhanced content security, Shanghai `profilePhotoCheck` | RAM AccessKey ID and AccessKey Secret |
|
||||
## Completion criteria and troubleshooting
|
||||
|
||||
For Xfyun, APIKey maps to `access-key-id` and APISecret to `access-key-secret`; see the [provider API](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html). For Aliyun, consult [service onboarding](https://help.aliyun.com/zh/document_detail/467828.html) and grant the required `yundun-greenweb:DescribeUploadToken` and `yundun-greenweb:ImageModeration` permissions rather than full access to your own OSS buckets.
|
||||
Owners should see the submitted image and status on the update page. Applications requiring review should be identifiable in the existing skill queue. After approval, public detail should display the newly active image. Upload completion, machine pass, human approval, and public-image activation are separate completion criteria.
|
||||
|
||||
Aliyun uses temporary upload credentials and synchronous moderation; no dedicated user-managed moderation bucket is required. This is independent of SkillHub's package/avatar storage. The adapter maps `none/low` risk to pass and `medium/high` to block; unknown, empty or failed responses do not pass. Treating `medium` as requiring review is SkillHub policy.
|
||||
|
||||
### Supply credentials through a private environment file
|
||||
|
||||
First configure the normal release stack. Outside the repository, create a private directory such as `/etc/skillhub/private` (suggested permissions: directory `700`, files `600`). Replace the path with your own. Standard Compose only passes declared settings; adding arbitrary values to `.env.release` does not inject them into the server.
|
||||
|
||||
Create `avatar-moderation.env` with **one** provider configuration. Replace placeholders and keep `SPRING_APPLICATION_JSON` as valid single-line JSON:
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}}
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}}
|
||||
```
|
||||
|
||||
If you already use `SPRING_APPLICATION_JSON`, merge this subtree into it; do not replace other configuration or define duplicate variables. An override's `environment` takes precedence over `env_file`. Escape credential characters correctly for JSON.
|
||||
|
||||
Create `compose.avatar.yml` in the same private directory:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
server:
|
||||
env_file:
|
||||
- /etc/skillhub/private/avatar-moderation.env
|
||||
```
|
||||
|
||||
From the repository root, retain your deployment's existing project name, Compose files and other options, then append the override:
|
||||
|
||||
```bash
|
||||
make validate-release-config
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
up -d --no-deps server
|
||||
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
ps server
|
||||
```
|
||||
|
||||
This updates an existing full stack. For initial deployment, use `up -d` instead of `up -d --no-deps server`. A restart does not reload changed container environments; recreate the service and preserve the override in future updates. Other platforms should inject the same `skillhub.avatar.moderation` properties through their secret mechanism.
|
||||
|
||||
::: warning Xfyun outbound logging
|
||||
The Xfyun interface carries `accessKeySecret` in URL parameters. The adapter avoids logging complete URLs and raw exceptions. Also disable HTTP debug logging and prevent proxies, tracing and external log collectors from capturing that request URL. Never share rendered secret-bearing Compose configuration or container environments.
|
||||
:::
|
||||
|
||||
### Enable and verify actual moderation
|
||||
|
||||
1. After server health checks pass, open System Configuration as a super administrator.
|
||||
2. Enable machine moderation; retaining manual review initially makes decisions observable.
|
||||
3. As a skill owner, submit a **new** avatar for a non-PRIVATE test skill.
|
||||
4. Inspect the machine result on the update page. If manual review is enabled, review its image and result in the skill review queue.
|
||||
5. Verify pass, block and error handling: the old public image remains until approval, blocked/error candidates stay private, and manual rejection has a visible reason. Do not approve prohibited content merely for testing.
|
||||
|
||||
Saving credentials or enabling a switch checks configuration completeness, not real account permissions, connectivity, quota or responses. Existing candidates are not automatically rescanned after enabling a switch. Code and simulated tests do not replace acceptance with your own deployment account; verify connectivity, result mapping and failure handling after setup or credential rotation.
|
||||
|
||||
## Provider changes and retention
|
||||
|
||||
Candidates retain snapshots of their machine/manual switches and provider. Later setting changes do not rewrite old candidates. Before switching providers, finish pending reviews; update private configuration, recreate the server, then submit new candidates. Completed results are not rerun. If an old candidate still requires its old provider after a switch, it errors rather than silently using the new provider.
|
||||
|
||||
Rejected, replaced or deleted candidates are privately retained for 30 days before cleanup; textual review records remain. Provider-side temporary-upload retention is separate.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check |
|
||||
| --- | --- |
|
||||
| Provider unavailable when enabling | Provider spelling, required credentials and whether the correct override was used; do not print all environment values |
|
||||
| Repeated machine errors | Server connectivity, account permissions, enabled service and quota; Aliyun also needs its temporary OSS upload endpoint. Wait for cooldown before retrying |
|
||||
| Manual moderation disabled but package still needs review | The avatar switch does not change package review rules |
|
||||
| Other users see the old image | Expected while the new candidate is pending; owners inspect candidates in My Skills/update, public detail shows the active avatar |
|
||||
| Symptom | Likely cause | Diagnostic action | Resolution |
|
||||
| --- | --- | --- | --- |
|
||||
| Avatar cannot be submitted | Failed upload, invalid image, or expired reference | Read the upload error and compare input limits and reference time | Crop and upload again; do not change only the extension to bypass validation |
|
||||
| Public detail retains the old image | New candidate is pending or inactive | Compare the candidate and its machine/manual states in My Skills or Update | Track the current application; do not repeatedly submit the same image instead of querying its state |
|
||||
| Machine errors persist | Configuration, dependency, or provider failure | Read `ERROR` and retry time; deployment operators inspect service configuration | Retry after recovery and cooldown; do not approve an error as a pass |
|
||||
| Package still awaits review with manual moderation off | Avatar switches do not control package review | Check whether the application also contains a package and inspect its state | Complete the normal skill review; do not force publication through database changes |
|
||||
| A suspected false positive cannot activate | Blocked candidate needs human review or an explicit reason | Inspect `BLOCKED`, the manual switch, and review state | The owner requests review; an authorized reviewer evaluates evidence. Do not switch accounts to bypass moderation |
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Find a skill in an existing registry, inspect an available version, then install
|
|||
|
||||
## Before you start
|
||||
|
||||
Public skills can be browsed anonymously. For team or private resources, sign in to the correct instance and confirm namespace permissions. See [Quick Start](../quickstart.md) for CLI and Agent setup. Paths below are relative to your deployment, not a fixed development port.
|
||||
Public (`PUBLIC`) skills can be browsed anonymously. Searching namespace-only (`NAMESPACE_ONLY`) skills requires sign-in to the correct instance and the relevant membership. Ordinary marketplace search excludes private (`PRIVATE`) skills; owners manage them in My Skills instead of repeatedly changing search terms. See the [full-text query implementation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-search/src/main/java/com/iflytek/skillhub/search/postgres/PostgresFullTextQueryService.java). See [Quick Start](../quickstart.md) for CLI and Agent setup. Paths below are relative to your deployment, not a fixed development port.
|
||||
|
||||
## Search in the Web UI
|
||||
|
||||
|
|
|
|||
|
|
@ -275,7 +275,9 @@ A: SkillHub 默认的 Compose 和 `runtime.sh` 使用 Docker named volume（`pos
|
|||
|
||||
## Q: 通过 OAuth（GitHub / GitLab 等）登录的账号，如何取得管理员权限？
|
||||
|
||||
A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`（例如初始化时的 bootstrap admin）在后台将其提升为管理员。
|
||||
A: 外部登录先按实例现有准入策略处理。首次创建且状态为 `ACTIVE` 的外部账号，如果身份来源提供已验证邮箱，并匹配启用的首次授权规则，可获得该规则配置的平台角色；没有匹配规则时不自动授予平台管理权限。规则仅在新账号创建时执行，不追溯已有账号，也不因邮箱相同而合并账号。已有账号由具有相应权限的平台角色在用户管理中授权；超级管理员（SUPER_ADMIN）的授予须由超级管理员执行。
|
||||
|
||||
规则入口与操作说明见[账号与访问令牌](./guide/account-access.html)；执行条件见[首次外部授权服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/settings/InitialExternalRoleGrantService.java)及[账号创建流程](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/identity/IdentityBindingService.java)。
|
||||
|
||||
`USER_ADMIN` 可以管理用户状态，并分配除 `SUPER_ADMIN` 之外的平台角色；但不能向任何账号授予 `SUPER_ADMIN`，也不能修改已有 `SUPER_ADMIN` 账号的角色。这两类操作只有 `SUPER_ADMIN` 可以执行。
|
||||
|
||||
|
|
|
|||
123
docs/skillhub/guide/avatar-moderation-configuration.md
Normal file
123
docs/skillhub/guide/avatar-moderation-configuration.md
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
# 配置头像机器审核服务
|
||||
|
||||
本页面向具有部署权限的操作者，说明头像图片审核供应商的服务开通、凭据注入、服务更新与实际调用核验。部署前须已有可运行的注册中心及包含本功能的镜像；本页不部署独立审核引擎，不说明技能所有者的上传操作。头像提交、策略与审核入口见[技能头像与审核](./skill-avatars.html)。
|
||||
|
||||
|
||||
## 前置条件与职责
|
||||
|
||||
| 操作 | 执行主体 | 前置与完成依据 |
|
||||
| --- | --- | --- |
|
||||
| 注入凭据和更新容器 | 具有部署权限的操作者 | 原注册中心正常运行，能够使用其部署目录和私有配置；更新的是原项目服务 |
|
||||
| 开启审核策略 | 超级管理员（SUPER_ADMIN） | 配置齐全后在系统配置保存开关；保存成功不代表云服务调用成功 |
|
||||
| 产生验收候选 | 技能所有者 | 向非私有测试技能提交新头像；不复用旧申请推断接入结果 |
|
||||
| 核对审核与公开结果 | 有权技能审核人 | 在原技能申请中核对图片及机器结果；不得为验收批准违规内容 |
|
||||
|
||||
## 选择供应商并确认权限
|
||||
|
||||
每个服务部署只选择一个：`xfyun` 或 `aliyun`。供应商及凭证在应用启动时读取；后台仅能启停审核，不能切换供应商。不开启机器审核时无需提供云审核凭证。
|
||||
|
||||
| 供应商 | 需要开通的服务 | 所需凭证 |
|
||||
| --- | --- | --- |
|
||||
| 讯飞 | 图片合规审核 | APPID、APIKey、APISecret |
|
||||
| 阿里云 | 内容安全增强版，上海地域的头像图片检测 `profilePhotoCheck` | RAM 用户的 AccessKey ID、AccessKey Secret |
|
||||
|
||||
服务开通、额度及计费以供应商控制台为准；开启后真实调用可能产生费用。
|
||||
|
||||
- 讯飞：[官方图片合规服务接入与鉴权说明](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html)。APIKey 对应 `access-key-id`，APISecret 对应 `access-key-secret`。
|
||||
- 阿里云：[内容安全控制台](https://yundun.console.aliyun.com/?p=cts)、[开通服务与创建 RAM 用户的官方接入步骤](https://help.aliyun.com/zh/document_detail/467828.html)。按最小权限配置 `yundun-greenweb:DescribeUploadToken` 和 `yundun-greenweb:ImageModeration`，不需要给审核用户自有 OSS 全权限。
|
||||
|
||||
阿里云适配器通过官方临时上传令牌上传私有图片，再调用同步审核，**无需自建审核用 OSS Bucket**。它与 SkillHub 自己保存技能和头像的对象存储配置相互独立。当前将 `RiskLevel=none/low` 视为通过，`medium/high` 视为阻止，机器阻止后的人工处理遵循头像审核策略，不代表供应商已经作出最终人工决定。空结果、未知值及接口失败均不放行。参考[官方接口说明](https://help.aliyun.com/document_detail/467829.html)。
|
||||
|
||||
## 注入私有配置并重新创建服务
|
||||
|
||||
下面使用仓库标准 `compose.release.yml` 的 `server` 服务。先按现有部署流程准备 `.env.release`、数据库及 SkillHub 对象存储，选用包含本功能的镜像版本。本节不会替换原部署设置。
|
||||
|
||||
在仓库外建立私有目录，将示例路径 `/etc/skillhub/private` 换成实际路径。以下是本页采用的操作系统权限示例，不是应用配置默认值；不得把凭据文件提交到 Git。
|
||||
|
||||
| 操作对象 | 本页权限示例 | 生效方式与边界 |
|
||||
| --- | --- | --- |
|
||||
| 私有目录 | `700` | 由部署方设置文件系统权限，仅目录所有者访问 |
|
||||
| 凭据与 override 文件 | `600` | 由部署方设置文件系统权限，仅文件所有者读写 |
|
||||
|
||||
|
||||
标准 Compose 只透传它声明的环境变量；仅向 `.env.release` 添加新审核属性不会自动注入 `server`。以下通过额外 override 的 `env_file` 显式注入，原 Compose 模板没有内置这些凭证字段。
|
||||
|
||||
创建 `/etc/skillhub/private/avatar-moderation.env`，以下两种内容**二选一**。占位符需替换为实际凭证；`SPRING_APPLICATION_JSON` 必须是单行合法 JSON。
|
||||
|
||||
**讯飞：**
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}}
|
||||
```
|
||||
|
||||
**阿里云：**
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}}
|
||||
```
|
||||
|
||||
如果部署已有 `SPRING_APPLICATION_JSON`，**将上述 `skillhub.avatar.moderation` 合并进原 JSON，不要覆盖原配置或设置重复变量**；其他 override 若通过 `environment` 定义同名变量，会优先于 `env_file`，也需同步合并。特殊字符应按 JSON 格式转义。
|
||||
|
||||
在同一私有目录创建 `compose.avatar.yml`：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
server:
|
||||
env_file:
|
||||
- /etc/skillhub/private/avatar-moderation.env
|
||||
```
|
||||
|
||||
然后在仓库根目录执行。已有部署若使用额外 Compose 文件、`-p` 项目名或其他启动参数，保留这些参数，再追加头像 override，确保更新原服务：
|
||||
|
||||
```bash
|
||||
make validate-release-config
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
up -d --no-deps server
|
||||
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
ps server
|
||||
```
|
||||
|
||||
上述更新命令适用于已运行的完整栈。首次部署完整栈时，将 `up -d --no-deps server` 改为 `up -d`。只执行 `restart` 不会重新加载修改后的容器环境，配置更新需要重新创建服务。后续更新也要保留同一 override。
|
||||
|
||||
正式 Spring 属性是 `skillhub.avatar.moderation.provider`、`skillhub.avatar.moderation.xfyun.app-id`、`skillhub.avatar.moderation.xfyun.access-key-id`、`skillhub.avatar.moderation.xfyun.access-key-secret`，以及 `skillhub.avatar.moderation.aliyun.access-key-id`、`skillhub.avatar.moderation.aliyun.access-key-secret`。其他部署平台可通过 Secret 注入同等属性。
|
||||
|
||||
::: warning 讯飞出口日志
|
||||
讯飞官方接口将 `accessKeySecret` 放在请求 URL 参数中。应用不记录完整 URL 或异常原文，但部署方仍需关闭 HTTP 客户端调试日志，并确保出口代理、链路追踪及第三方日志不采集该请求 URL。不要把含凭证的 Compose 展开结果、容器环境或签名请求 URL 分享给其他人。
|
||||
:::
|
||||
|
||||
## 开启审核并核验实际结果
|
||||
|
||||
1. 确认 `server` 健康后，以超级管理员进入「系统配置」。
|
||||
2. 开启机器审核，初次接入时保留人工审核开启，以便核对机器结果与人工决定。
|
||||
3. 用技能所有者账号对一个非 `PRIVATE` 测试技能提交**新头像**。
|
||||
4. 在更新页查看机器结果；开启人工时，审核员在技能审核详情中确认图片、机器状态并做出决定。
|
||||
5. 对通过、阻止、异常分别检查：通过前旧公开头像不变，阻止或异常的新图片不可公开，人工拒绝后可见原因。不要为了测试把违规图片批准公开。
|
||||
|
||||
填写凭证、成功保存开关或应用健康，均不能证明云服务调用成功。后台检查的是配置是否齐全，真正的服务权限、网络、余额和接口响应必须通过新申请验证。已有申请不因开关开启而补跑机器审核。
|
||||
|
||||
供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。
|
||||
|
||||
## 切换供应商与已有申请
|
||||
|
||||
每次申请保存提交时的机器、人工开关和供应商快照。后续配置变更不会回写已有申请，也不会重跑已完成结果。切换前，先由有权审核人处理待审申请；更新私有配置、重新创建 `server` 后，由技能所有者提交新申请以使用新供应商。
|
||||
|
||||
旧候选仍需调用旧供应商时，切换后会得到 `ERROR`，不会改用新供应商。不得仅更新后台开关后认定旧任务已经恢复。SkillHub 候选图片保留规则见[技能头像与审核](./skill-avatars.html)；供应商临时上传图片的生命周期属于外部服务规则，二者不能互相替代。
|
||||
|
||||
## 结果确认与失败处置
|
||||
|
||||
后台允许开启机器审核，仅表示所选供应商的必要配置齐全。完成接入须以新申请的实际机器结果和候选图片可见性为依据；服务健康、填写凭证与保存开关均不能替代真实调用核验。
|
||||
|
||||
| 现象 | 最可能原因 | 定位手段 | 处置 |
|
||||
| --- | --- | --- | --- |
|
||||
| 开启时提示供应商不可用 | `provider` 拼写错误或凭据未注入 | 核对私有文件中的属性名及启动命令是否包含相同 override | 修正配置并重新创建原服务；不要输出完整环境变量或 Secret |
|
||||
| 配置修改后行为未变 | 仅重启容器，或同名变量被覆盖 | 比较实际启动使用的 Compose 文件顺序及 `environment`/`env_file` 定义 | 合并同名 JSON 并重新创建服务；不要覆盖其他 Spring 配置 |
|
||||
| 新申请机器结果为 `ERROR` | 服务未开通、权限、额度或出口网络异常 | 核对新申请机器状态及供应商控制台权限、服务和额度；阿里云还需检查临时 OSS 上传端点可达性 | 恢复依赖后按冷却规则重试；不要将异常当作允许 |
|
||||
| 切换后旧候选持续异常 | 申请保存的供应商与当前部署不一致 | 比较候选所用供应商和当前 `provider` | 处理旧申请或重新提交；不要直接修改候选快照 |
|
||||
| 开启机器审核后旧申请没有新结果 | 开关不追溯已有申请 | 在更新页核对申请时间、机器状态及本次候选 | 使用新申请验证；不要为生成调用重复批准旧申请 |
|
||||
|
||||
配置绑定及供应商选择依据：[供应商网关](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AvatarModerationGateway.java)、[讯飞适配器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/XfyunAvatarModerationProvider.java)和[阿里云适配器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AliyunAvatarModerationProvider.java)。本页命令以[release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml)为基线；其他部署路径须通过其 Secret 机制注入相同属性，不得直接套用 Compose 更新命令。
|
||||
|
|
@ -445,13 +445,10 @@ skillhub remove pdf-parser --json
|
|||
skillhub doctor --json
|
||||
```
|
||||
|
||||
成功响应格式：
|
||||
以下为成功标志的 JSON 节选，不是完整命令响应；结果字段取决于命令：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
...
|
||||
}
|
||||
{"ok": true}
|
||||
```
|
||||
|
||||
错误响应格式：
|
||||
|
|
@ -666,15 +663,14 @@ skillhub search test --registry https://skillhub.example.com
|
|||
|
||||
### 安装目录冲突
|
||||
|
||||
```bash
|
||||
# 使用 --force 覆盖
|
||||
skillhub install pdf-parser --force
|
||||
先核对当前注册中心、目标 Agent 和安装目录，再检查现有文件的来源及本地修改。以下以 Codex 为例；其他 Agent 应使用实际标识。
|
||||
|
||||
# 或先删除再安装
|
||||
skillhub remove pdf-parser
|
||||
skillhub install pdf-parser
|
||||
```bash
|
||||
skillhub list --agent codex --json
|
||||
```
|
||||
|
||||
将记录中的 `installDir` 与冲突路径比较，并读取该目录的 `SKILL.md`。确认属于同一安装来源、完成备份且明确允许舍弃本地改动后，才可按更新计划使用 `--force`。该参数不能接管未管理目录、其他来源或已停用目标。无法确认来源时，应选择不同的目录或安装范围，不得直接删除文件或安装记录排障。
|
||||
|
||||
### 清单损坏
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
## 使用技能
|
||||
|
||||
| 你要做什么 | 阅读 |
|
||||
| 操作目标 | 阅读 |
|
||||
| --- | --- |
|
||||
| 找到适合任务的技能，查看版本和权限 | [搜索与安装技能](./skill-discovery.html) |
|
||||
| 一次安装一组固定版本技能，从入口技能开始使用 | [管理技能套装](./skill-suites.html) |
|
||||
|
|
@ -30,6 +30,7 @@
|
|||
- [管理命名空间](./namespace.html)：成员、角色和资源可见范围。
|
||||
- [审核技能与套装](./review.html)：处理技能与套装申请。
|
||||
- [安全扫描与报告](./scanner.html)：扫描服务接入及结果解读。
|
||||
- [技能头像与审核](./skill-avatars.html)：技能所有者提交头像，有权审核人处理申请，超级管理员调整审核策略。
|
||||
|
||||
## 部署与运维
|
||||
|
||||
|
|
@ -38,7 +39,7 @@
|
|||
- [Docker 部署](./deployment.html)：安装、配置、升级和备份。
|
||||
- [Kubernetes 部署（Kustomize / Helm）](./kubernetes.html)：选择清单或独立 Chart 路径。
|
||||
- [前端动作统计](./frontend-analytics.html)：可选配置化接入、授权与故障验收，按部署版本选择配置。
|
||||
- [技能头像与审核](./skill-avatars.html)：管理员配置图片审核服务。
|
||||
- [配置头像机器审核服务](./avatar-moderation-configuration.html)：部署方选择供应商、注入凭据、更新服务并验证实际调用。
|
||||
|
||||
## 开发与集成
|
||||
|
||||
|
|
|
|||
|
|
@ -1,151 +1,80 @@
|
|||
# 技能头像：上传、审核与供应商配置
|
||||
# 技能头像与审核
|
||||
|
||||
本页介绍如何上传技能头像，以及部署方如何接入讯飞或阿里云图片审核。这是**技能头像**功能，不涉及用户个人头像；图片审核与技能包安全扫描是两种不同的检查。
|
||||
本页说明技能所有者如何提交头像，以及有权审核人如何处理头像申请。技能头像不包含用户个人头像；图片审核与技能包安全扫描是独立检查。供应商开通、凭据和容器更新由部署方负责，见[配置头像机器审核服务](./avatar-moderation-configuration.html)。
|
||||
|
||||
## 技能所有者怎么使用
|
||||
## 前置条件与职责
|
||||
|
||||
1. 新增技能时，在发布页选择自定义 PNG/JPEG；已有技能从「我的技能 → 更新」进入，也可只改头像而不发布新版本。
|
||||
2. 在裁剪弹窗调整方形区域和缩放，确认后等待上传成功。图片上传中或失败时不能提交；未选择头像也可正常提交，显示技能名首字母。
|
||||
3. 提交后，在「我的技能」或更新页查看**本次提交的图片**及审核状态。审核通过前，其他人继续看到旧头像或首字母。
|
||||
4. 被拒绝后查看原因，修改图片再提交。新申请会替换旧待审申请，旧审核结果不会覆盖新头像。
|
||||
操作前须登录同一注册中心，确认目标技能及当前账号。技能所有者维护头像，命名空间角色或平台角色不自动获得代传权限。
|
||||
|
||||
上传输入限 PNG/JPEG、2 MB、正方形且边长不超过 1024 像素；服务器会再次校验并重新编码为 PNG。上传成功仅表示图片已存入私有存储，不代表审核通过。临时上传引用 24 小时后过期，过期需要重新上传。
|
||||
|
||||
更新默认保留原头像，也可移除：单改头像提交成功后恢复首字母；与新技能包一起提交时，审核通过后才移除。取消编辑或提交失败不改变现有头像。技能详情和列表展示当前生效头像，不设单独的头像管理入口。
|
||||
|
||||
## 管理员怎么审核
|
||||
|
||||
头像与技能包同时提交时，共用一张技能申请，审核员在原审核详情中对内容和头像一次批准或拒绝。只改头像且需要人工决定时，也进入这个技能审核队列，标明「头像修改」，不创建新技能版本。
|
||||
|
||||
团队管理员审核本团队；平台技能管理员和超级管理员可审核团队及全局，自审权限沿用原技能审核规则。管理员可撤下头像，但不能替所有者上传新头像。
|
||||
|
||||
### 两个开关与四种流程
|
||||
|
||||
超级管理员在「系统配置」（`/dashboard/admin/system-config`）中选择「启用机器审核」与「启用人工审核」。默认机器关闭、人工开启。后台只管理这两个开关，不配置供应商、不显示密钥。
|
||||
|
||||
| 机器审核 | 人工审核 | 非 PRIVATE 技能单改头像的流程 |
|
||||
| 操作 | 执行主体 | 入口与边界 |
|
||||
| --- | --- | --- |
|
||||
| 关闭 | 关闭 | 提交成功后直接生效 |
|
||||
| 新增、替换或移除头像 | 技能所有者 | 发布页或“我的技能 → 更新”；可只改头像而不创建版本 |
|
||||
| 审核头像申请 | 对目标命名空间有审核权限的账号 | 原技能审核队列；头像与内容同次提交时共同决定 |
|
||||
| 调整机器、人工审核开关 | 超级管理员（SUPER_ADMIN） | `/dashboard/admin/system-config`；不在此填写凭据或切换供应商 |
|
||||
| 接入或切换供应商 | 具有部署权限的操作者 | 在部署配置中选择供应商并注入私有凭据 |
|
||||
|
||||
团队命名空间所有者（Owner）及空间管理员（Admin）审核本命名空间；平台技能管理员（SKILL_ADMIN）和超级管理员可审核团队及全局。自审限制沿用[技能审核规则](./review.html)，不得从平台角色推导全部自审权限。有权操作者可撤下头像，但不能代替所有者上传。
|
||||
|
||||
## 提交与更新头像
|
||||
|
||||
1. 在发布或更新表单选择自定义 PNG/JPEG，在裁剪弹窗调整方形区域与缩放。未选择图片时可正常提交，使用技能名首字母。
|
||||
2. 确认裁剪并等待上传结束。上传中或失败时不能提交；服务器会重新校验图片并编码为 PNG。上传成功只表示已存入私有存储，不代表审核已批准。
|
||||
3. 提交后，在“我的技能”或更新页核对本次候选图片及机器、人工状态。候选未生效时，公开详情和列表继续显示旧头像或首字母；不能据此认定提交丢失。
|
||||
4. 被拒绝后读取原因、修订图片并重新提交。新申请替换旧待审申请，旧审核结果不能覆盖新候选；申请记录继续留存。
|
||||
|
||||
更新默认保留原头像。单改头像的移除请求提交成功后恢复首字母；移除与新技能包同次提交时，须等待该申请获批。取消编辑或提交失败不改变现有头像，不设单独的头像管理入口。
|
||||
|
||||
## 审核策略与申请关系
|
||||
|
||||
头像与技能包同次提交时，共用一张技能申请，由审核人在原详情中一次批准或拒绝；头像不会提前发布。只改头像且需要人工决定时，同样进入技能审核队列，标记“头像修改”，不创建新技能版本。
|
||||
|
||||
超级管理员在系统配置中分别管理两个开关，默认机器关闭、人工开启。后台不配置供应商或显示密钥。下表适用于非私有技能的单改头像申请。
|
||||
|
||||
| 机器审核 | 人工审核 | 生效条件 |
|
||||
| --- | --- | --- |
|
||||
| 关闭 | 关闭 | 提交成功后生效 |
|
||||
| 关闭 | 开启 | 人工批准后生效 |
|
||||
| 开启 | 关闭 | 机器通过后自动生效；阻止或异常时不生效 |
|
||||
| 开启 | 开启 | 先机器审核，再由人工决定 |
|
||||
| 开启 | 关闭 | 机器允许后生效；阻止或异常不生效 |
|
||||
| 开启 | 开启 | 先完成机器审核，再由人工决定 |
|
||||
|
||||
**边界：**`PRIVATE` 技能头像仅所有者可读，直接使用，不运行上述机器或人工审核；扩大可见范围时需要按目标范围重新审核。头像与技能包同次提交时，不论头像开关如何，仍须等待原技能审核共同批准，不会提前发布头像。
|
||||
私有（PRIVATE）技能头像仅所有者可读，直接使用，不运行上述机器或人工审核；扩大可见范围时按目标范围重新审核。头像与技能包共同提交时，无论头像开关如何，均须等待原技能申请的批准。
|
||||
|
||||
### 违规会直接失败吗？
|
||||
## 机器结果与人工决定
|
||||
|
||||
机器结果与申请最终决定不同：
|
||||
| 机器结果 | 候选与公开头像 | 后续处理 |
|
||||
| --- | --- | --- |
|
||||
| `PASSED` | 有人工审核时仍待审；无人工审核时单改头像生效 | 审核人核对候选和目标申请，不能把机器允许作为内容效果保证 |
|
||||
| `BLOCKED` | 新图片保持私有，旧头像继续使用 | 有人工审核时可拒绝；认为误判而批准须填写明确理由；无人工审核时所有者可申请人工复核 |
|
||||
| `ERROR` | 新图片保持私有，不能直接批准 | 部署方排查配置、网络或供应商服务，恢复后重试 |
|
||||
|
||||
| 结果 | 处理 |
|
||||
| --- | --- |
|
||||
| `PASSED`（通过） | 有人工审核时继续待审；没有人工审核时单改头像自动生效 |
|
||||
| `BLOCKED`（阻止） | 新图片保持私有、旧头像继续使用。开启人工审核时继续待审，审核员可拒绝；认为误判时必须填写明确理由才能批准。未开启人工审核时不生效，所有者可申请人工复核 |
|
||||
| `ERROR`（异常） | 新图片保持私有，不能直接批准放行；先排查配置、网络或供应商服务，再重试 |
|
||||
机器阻止不等于文件上传失败，也不等于人工已拒绝。人工拒绝后，所有者可查看候选与原因；人工批准后须核对当前生效头像，不能仅凭任务文字判断最终图片。
|
||||
|
||||
因此，**机器判违规不等于文件上传失败，也不等于人工已拒绝申请**。人工拒绝后，所有者可查看提交图片与拒绝原因。异常自动重试有一小时冷却，同一候选最多自动调用三次（含首次）；耗尽后可在冷却结束后主动重试或重新提交。
|
||||
## 输入、重试与保留规则
|
||||
|
||||
| 项目 | 固定值或范围 | 生效与限制 |
|
||||
| --- | --- | --- |
|
||||
| 上传图片 | PNG/JPEG；不超过2MiB；正方形，边长不超过1024像素 | 上传时由服务器校验并重编码；越界提交被拒绝 |
|
||||
| 临时上传引用 | 24小时 | 过期须重新上传，不等于已提交候选的保留期 |
|
||||
| 机器异常冷却 | 1小时 | 错误结果后等待冷却；不得通过重复请求跳过 |
|
||||
| 自动调用上限 | 同一候选共3次，含首次 | 耗尽后在冷却结束后主动重试或重新提交 |
|
||||
| 已丢弃候选图片 | 被拒绝、替换或移除后私有保留30天 | 到期由清理任务删除图片，文字记录继续保留；不承诺精确到期时刻 |
|
||||
|
||||
申请保留提交时的机器、人工开关和供应商快照，后续改开关不会回写已有申请。已完成的机器结果不自动重跑；供应商变更后，旧候选仍需旧供应商时可能为 `ERROR`，须由部署方与审核人协调处理，或重新提交新申请。
|
||||
|
||||
规则依据：[上传与引用](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarUploadService.java)、[图片校验](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarImageProcessor.java)、[候选状态](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java)及[头像流程](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarAppService.java)。
|
||||
|
||||
## 部署方如何接入机器审核
|
||||
|
||||
### 1. 选择一个供应商
|
||||
每个部署选择一个供应商，凭据在服务启动时读取；后台只能管理审核开关，不能通过保存开关验证云账号权限、网络或额度。接入、轮换与切换由部署方按[配置头像机器审核服务](./avatar-moderation-configuration.html)执行，并使用新申请验证实际调用。
|
||||
|
||||
每个服务部署只选择一个：`xfyun` 或 `aliyun`。供应商及凭证在应用启动时读取；后台仅能启停审核，不能切换供应商。不开启机器审核时无需提供云审核凭证。
|
||||
## 完成标准与失败处置
|
||||
|
||||
| 供应商 | 需要开通的服务 | 所需凭证 |
|
||||
| --- | --- | --- |
|
||||
| 讯飞 | 图片合规审核 | APPID、APIKey、APISecret |
|
||||
| 阿里云 | 内容安全增强版，上海地域的头像图片检测 `profilePhotoCheck` | RAM 用户的 AccessKey ID、AccessKey Secret |
|
||||
所有者应能在更新页看到本次提交的图片及状态；需要审核的申请应在原技能队列可定位；批准后，公开详情显示本次生效头像。上传完成、机器允许、人工批准和公开头像切换是不同完成标志。
|
||||
|
||||
服务开通、额度及计费以供应商控制台为准；开启后真实调用可能产生费用。
|
||||
|
||||
- 讯飞：[官方图片合规服务接入与鉴权说明](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html)。注意 APIKey 对应 `access-key-id`，APISecret 对应 `access-key-secret`。
|
||||
- 阿里云：[内容安全控制台](https://yundun.console.aliyun.com/?p=cts)、[开通服务与创建 RAM 用户的官方接入步骤](https://help.aliyun.com/zh/document_detail/467828.html)。按最小权限配置 `yundun-greenweb:DescribeUploadToken` 和 `yundun-greenweb:ImageModeration`，不需要给审核用户自有 OSS 全权限。
|
||||
|
||||
阿里云适配器通过官方临时上传令牌上传私有图片，再调用同步审核，**无需自建审核用 OSS Bucket**。它与 SkillHub 自己保存技能和头像的对象存储配置相互独立。当前将 `RiskLevel=none/low` 视为通过，`medium/high` 视为阻止，其中 `medium` 转人工复核是 SkillHub 的策略。空结果、未知值及接口失败均不放行。参考[官方接口说明](https://help.aliyun.com/document_detail/467829.html)。
|
||||
|
||||
### 2. 用私有环境文件提供凭证
|
||||
|
||||
下面使用仓库标准 `compose.release.yml` 的 `server` 服务。先按现有部署流程准备 `.env.release`、数据库及 SkillHub 对象存储，选用包含本功能的镜像版本。本节不会替换原部署设置。
|
||||
|
||||
在**仓库外**建立私有目录，将下面路径中的 `/etc/skillhub/private` 换成实际路径；目录权限建议 `700`，文件权限 `600`。不要把凭证文件提交到 Git。
|
||||
|
||||
标准 Compose 只透传它声明的环境变量；仅向 `.env.release` 添加新审核属性不会自动注入 `server`。以下通过额外 override 的 `env_file` 显式注入，原 Compose 模板没有内置这些凭证字段。
|
||||
|
||||
创建 `/etc/skillhub/private/avatar-moderation.env`，以下两种内容**二选一**。占位符需替换为实际凭证；`SPRING_APPLICATION_JSON` 必须是单行合法 JSON。
|
||||
|
||||
**讯飞：**
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}}
|
||||
```
|
||||
|
||||
**阿里云：**
|
||||
|
||||
```dotenv
|
||||
SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}}
|
||||
```
|
||||
|
||||
如果部署已有 `SPRING_APPLICATION_JSON`，**将上述 `skillhub.avatar.moderation` 合并进原 JSON，不要覆盖原配置或设置重复变量**；其他 override 若通过 `environment` 定义同名变量，会优先于 `env_file`，也需同步合并。特殊字符应按 JSON 格式转义。
|
||||
|
||||
在同一私有目录创建 `compose.avatar.yml`：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
server:
|
||||
env_file:
|
||||
- /etc/skillhub/private/avatar-moderation.env
|
||||
```
|
||||
|
||||
然后在仓库根目录执行。已有部署若使用额外 Compose 文件、`-p` 项目名或其他启动参数，保留这些参数，再追加头像 override，确保更新原服务：
|
||||
|
||||
```bash
|
||||
make validate-release-config
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
up -d --no-deps server
|
||||
|
||||
docker compose --env-file .env.release \
|
||||
-f compose.release.yml \
|
||||
-f /etc/skillhub/private/compose.avatar.yml \
|
||||
ps server
|
||||
```
|
||||
|
||||
上述更新命令适用于已运行的完整栈。首次部署完整栈时，将 `up -d --no-deps server` 改为 `up -d`。只执行 `restart` 不会重新加载修改后的容器环境，配置更新需要重新创建服务。后续更新也要保留同一 override。
|
||||
|
||||
正式 Spring 属性是 `skillhub.avatar.moderation.provider`、`skillhub.avatar.moderation.xfyun.app-id`、`skillhub.avatar.moderation.xfyun.access-key-id`、`skillhub.avatar.moderation.xfyun.access-key-secret`，以及 `skillhub.avatar.moderation.aliyun.access-key-id`、`skillhub.avatar.moderation.aliyun.access-key-secret`。其他部署平台可通过 Secret 注入同等属性。
|
||||
|
||||
::: warning 讯飞出口日志
|
||||
讯飞官方接口将 `accessKeySecret` 放在请求 URL 参数中。应用不记录完整 URL 或异常原文，但部署方仍需关闭 HTTP 客户端调试日志，并确保出口代理、链路追踪及第三方日志不采集该请求 URL。不要把含凭证的 Compose 展开结果、容器环境或签名请求 URL 分享给其他人。
|
||||
:::
|
||||
|
||||
### 3. 在后台开启，并验证真实调用
|
||||
|
||||
1. 确认 `server` 健康后，以超级管理员进入「系统配置」。
|
||||
2. 开启机器审核，建议初次接入时保留人工审核开启。
|
||||
3. 用技能所有者账号对一个非 `PRIVATE` 测试技能提交**新头像**。
|
||||
4. 在更新页查看机器结果；开启人工时，审核员在技能审核详情中确认图片、机器状态并做出决定。
|
||||
5. 对通过、阻止、异常分别检查：通过前旧公开头像不变，阻止或异常的新图片不可公开，人工拒绝后可见原因。不要为了测试把违规图片批准公开。
|
||||
|
||||
填写凭证、成功保存开关或应用健康，**都不能证明云服务调用成功**。后台检查的是配置是否齐全，真正的服务权限、网络、余额和接口响应必须通过新申请验证。已有申请不因开关开启而补跑机器审核。
|
||||
|
||||
供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。
|
||||
|
||||
## 修改开关与切换供应商
|
||||
|
||||
申请保存提交时的机器、人工开关和供应商快照，之后改配置不会回写已有申请。若要切换供应商，应更新私有配置并重新创建 `server`，再提交新申请：
|
||||
|
||||
- 已完成的机器结果不会自动重新检测。
|
||||
- 旧候选仍需调用旧供应商时，切换后会得到 `ERROR`，不会偷偷改用新供应商；应重新提交以采用新供应商。
|
||||
- 配置切换前先处理待审申请，避免把旧任务留在不可继续审核的状态。
|
||||
|
||||
被拒绝、替换或删除的候选图片私有保留 30 天后清理，文字审核记录继续保留。云审核服务自己的临时图片生命周期与 SkillHub 私有保留规则不同。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**开启失败提示供应商不可用？** 检查 `provider` 拼写、所选供应商凭证是否齐全，以及额外 override 是否实际用于启动 `server`。不要通过输出完整环境变量排查密钥。
|
||||
|
||||
**上传成功但一直异常？** 检查服务器能否访问对应云接口、凭证权限、服务是否开通及可用额度；阿里云还需要能访问其临时 OSS 上传端点。等待冷却后重试，不要把异常当通过。
|
||||
|
||||
**人工开关关闭就不审核技能包了吗？** 不是。这个开关只控制头像的人工策略，不改变原技能包审核流程。
|
||||
|
||||
**为什么其他人仍看到旧头像？** 新申请未通过时这是正常行为；所有者应到「我的技能」或更新页查看提交图片，公开详情只展示当前生效头像。
|
||||
| 现象 | 最可能原因 | 定位手段 | 处置 |
|
||||
| --- | --- | --- | --- |
|
||||
| 无法提交头像 | 上传失败、格式越界或引用过期 | 查看上传错误，核对本页输入规则和引用时间 | 重新裁剪上传；不要仅修改文件扩展名规避校验 |
|
||||
| 公开详情仍是旧图片 | 新候选仍待审或未生效 | 在“我的技能”或更新页比较候选和机器、人工状态 | 跟踪当前申请；不要反复提交相同图片代替查询 |
|
||||
| 机器结果持续异常 | 配置、依赖或供应商故障 | 更新页读取 `ERROR` 和可重试时间，由部署方核对服务配置 | 故障恢复并过冷却后重试；不要将异常批准放行 |
|
||||
| 关闭人工后技能包仍待审 | 头像开关不控制技能包审核 | 核对是否同时提交技能包及该申请状态 | 按原技能审核完成内容决定；不要修改数据库强制发布 |
|
||||
| 认为机器误判但无法生效 | 候选被阻止，需要人工复核或明确理由 | 核对 `BLOCKED`、人工开关和当前复核状态 | 所有者发起复核，有权审核人依据证据处理；不要通过换账号绕过审核 |
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## 开始前
|
||||
|
||||
公开技能可匿名浏览。查找团队或私有资源时先登录正确实例，并确认拥有对应命名空间权限。准备 CLI 和 Agent 的步骤见[快速开始](../quickstart.md)。以下路径相对于实际部署地址，不固定开发端口。
|
||||
公开（PUBLIC）技能可匿名浏览；检索空间成员可见（NAMESPACE_ONLY）技能时，须登录正确实例并具备对应成员资格。普通市场搜索不收录私有（PRIVATE）技能，所有者须从“我的技能”查看和管理，不应通过反复修改关键词排查私有技能。搜索边界见[全文搜索查询](https://github.com/iflytek/skillhub/blob/main/server/skillhub-search/src/main/java/com/iflytek/skillhub/search/postgres/PostgresFullTextQueryService.java)。准备 CLI 和 Agent 的步骤见[快速开始](../quickstart.md)。以下路径相对于实际部署地址，不固定开发端口。
|
||||
|
||||
## 在网页查找
|
||||
|
||||
|
|
|
|||
|
|
@ -34,3 +34,13 @@ A2 的 29 项导航不是本 PR 的发布承诺；P1/P2、D10 全页深度改造
|
|||
- 每页记录来源与D1九要素覆盖；不明确的保留期、权限、事件类别、扫描阈值必须查代码，不编造固定承诺。无固定值时明确配置来源或未定义行为。
|
||||
|
||||
验收：中文正文体量不超过3000汉字（参考/代码清单不以扩写为目标），没有禁用旧章节或空标题；中英结构/链接一致；所有新技术断言有稳定源码依据；OpenSpec、VitePress、正文链接/锚点及真实浏览器宽度/主题检查通过，一次集中独立Review完成后冻结。
|
||||
|
||||
## 维护者复核补充：图片对齐与页面职责
|
||||
|
||||
维护者指出流程图应居中，以及头像上传/审核与供应商部署配置混放导致导航归属不合理。作为本批明确反馈的优先修正，文档主题仅为正文流程图补充水平居中样式，复用默认主题的自然尺寸与响应式规则，不改变其他界面。
|
||||
|
||||
头像原页面和URL保留，承载技能所有者及审核角色的操作并归入“团队与治理”；供应商开通、部署凭据、配置注入及真实连接验证拆至独立部署页面，归入“部署与运维”。中英文页面、导航索引及侧边栏同步，Pager由既有侧边栏顺序生成；不提前重排其余第三批导航。新页原有配置细节不得因拆分而丢失。
|
||||
|
||||
审查结论必须标注范围：六页正文增量的技术事实核查不代表全站信息架构或其余页面已通过。补充逐页结构台账，列明已修复、仍有缺口、未核实项目；源文件/浏览器自动检查仅证明相应结构与运行结果，不替代操作语义或未执行的真实外部服务验收。第三至第五批既有问题保持待办，不以“已排期”替代缺陷记录。
|
||||
|
||||
全站结构补查同时确认四项可定位的内容缺陷，作为本次反馈的局部事实修正：FAQ遗漏新外部账号的首次角色授权规则；搜索指南误导私有技能可在普通市场搜索；CLI成功JSON示例含裸省略号；目录冲突排障未就地明确来源核对和备份前置。中英文对应段落同步修正，并保留这些页面尚未完成整体深度/结构改造的状态，不将局部修正视为整页规范通过。
|
||||
|
|
|
|||
|
|
@ -34,3 +34,10 @@
|
|||
|
||||
|
||||
第二批验证摘要：12个中英文页面、12张SVG，正式文体、来源路径、58个正文链接及示例语法检查通过；OpenSpec严格校验与VitePress构建通过。浏览器首次48次页面检查，图示尺寸修正后补跑受影响页面32次，明暗主题、390px布局、图片加载、图内文字边界及主题/导航交互通过。扫描诊断92项受控回归通过；教程参数失败命令实际返回退出码5且网络调用0次。独立Review未发现实质事实问题；本地视觉检查发现的图示过度放大已修正。不代表实际安装、Agent执行、通知投递或真实部署已验收。第三至第五批仍未完成，第二批不自动合并或发布。
|
||||
|
||||
## 5. 维护者复核补充
|
||||
- [ ] VISUAL-CENTER 正文流程图水平居中，保留自然尺寸及移动缩放；浏览器检查实际几何位置。
|
||||
- [ ] IA-AVATAR 技能头像上传/审核与供应商部署分页面、分导航职责，中英/导航/Pager/交叉链接同步。
|
||||
- [ ] SITE-AUDIT 逐页核查站点结构、目标读者、导航归属、文书缺口并标注已修/待修/未核实；不得将增量Review汇报为整站通过。
|
||||
- [ ] 对上述增量独立复核，并更新构建、链接、浏览器及交付说明。
|
||||
- [ ] FACT-SPOT 全站补查发现的首次角色授权、私有搜索边界、CLI JSON与冲突处置四项问题完成双语局部修正，并保留其余页面缺口。
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue