thanhnvandClaude Opus 5
42f4a058ea
- Add QToolButton help icon (?) next to Project Mapping label - Implement comprehensive tooltip explaining Project ID and Jira Key concepts - Add inline validation to detect common mistake: entering issue keys (ABC-123) instead of project keys (ABC) - Add 13 new i18n keys for help text in English, Vietnamese, and Japanese - Add 15 comprehensive UX tests covering icon presence, tooltip content, validation logic, and accessibility - Update jira-knowledge-guide.md with help icon reference and setup instructions - Fix missing _on_paste method that was causing AttributeError Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
105 lines
5.5 KiB
Markdown
105 lines
5.5 KiB
Markdown
# Jira Project Knowledge - Production Guide
|
|
|
|
This guide covers the setup, operation, and troubleshooting of the Jira Project Knowledge capability in Cowork Local.
|
|
|
|
## 1. Architecture Overview
|
|
|
|
Jira Project Knowledge enables Cowork to index Jira issues as searchable project knowledge. The flow is:
|
|
|
|
1. **Configuration**: User maps a Cowork project to a Jira project key via UI.
|
|
2. **Sync**: `JiraSyncService` fetches issues from Jira using the configured credentials.
|
|
3. **Normalization**: Raw Jira JSON is converted to `CanonicalJiraIssue` (stripping markup, bounding content).
|
|
4. **Indexing**: Canonical issues are stored as atomic JSON files in `~/.cowork_local/jira_kb/<project_id>/issues/`.
|
|
5. **Retrieval**: `search_project_knowledge` MCP tool queries the local index using lexical scoring.
|
|
|
|
## 2. Prerequisites
|
|
|
|
* **Jira Access**: Read-only access to the target Jira project.
|
|
* **Credentials**:
|
|
* **Jira Cloud**: Email + API Token (from id.atlassian.com).
|
|
* **Jira Server/Data Center**: Personal Access Token (PAT) or Username/Password.
|
|
* **Python**: 3.10+ (for Pydantic v2 compatibility).
|
|
|
|
## 3. Setup & Configuration
|
|
|
|
### 3.1 Connect Jira
|
|
1. Open Cowork Local.
|
|
2. Go to **Monitoring** -> **Tools** -> **Jira**.
|
|
3. Enter **Base URL** (e.g., `https://your-domain.atlassian.net` or `https://jira.company.com`).
|
|
4. Enter **Email** (for Cloud) or **Username** (for Server).
|
|
5. Enter **API Token** or **PAT**.
|
|
6. Click **Test Connection**.
|
|
|
|
### 3.2 Enable Project Knowledge
|
|
1. In the same Jira dialog, check **Enable Jira Project Knowledge**.
|
|
2. Enter **Project Mapping** in the format `cowork_project_id:JIRA_PROJECT_KEY`.
|
|
* Example: `proj-alpha:ALPHA, proj-beta:BETA`
|
|
* Click the **ⓘ** icon next to "Project Mapping" for detailed help on:
|
|
* **Project ID**: The Cowork project identifier (e.g., `cowork-local`). Find it in your current Cowork project settings.
|
|
* **Jira Key**: The Jira project key (e.g., `ALPHA` from issue `ALPHA-123`). Open any Jira issue to find it.
|
|
* **Common mistake**: Do not enter issue keys like `ABC-123`. Only enter the project key part `ABC`.
|
|
3. Click **Save**.
|
|
|
|
### 3.3 Initial Sync
|
|
1. Click **Sync Now**.
|
|
2. Wait for the status to update to "Success: X issues synced".
|
|
3. The sync runs in the background; the UI remains responsive.
|
|
|
|
## 4. Usage
|
|
|
|
### 4.1 Search via Agent
|
|
Ask the agent questions about the project requirements or bugs. The agent will automatically use `search_project_knowledge` if Jira Knowledge is enabled for the current project.
|
|
|
|
* *Example*: "What are the acceptance criteria for the login feature?"
|
|
* *Example*: "Find bugs related to database timeout."
|
|
|
|
### 4.2 MCP Tool
|
|
The tool `search_project_knowledge` is available via the Project Context MCP server.
|
|
|
|
* **Input**: `project_id`, `query`, `top_k` (optional).
|
|
* **Output**: Ranked list of excerpts with Jira source URLs.
|
|
|
|
## 5. Security & Isolation
|
|
|
|
* **Read-Only**: The connector never writes to Jira.
|
|
* **Project Isolation**: Knowledge is strictly scoped by `project_id`. A user with access to Project A cannot search Project B's knowledge, even if they guess the project ID. The target resolver enforces this structurally.
|
|
* **Credential Safety**: Credentials are stored in the OS Keyring (via `SecretStore`), not in plain text config files (unless fallback is used). They are never logged or sent to the LLM.
|
|
* **Untrusted Content**: Jira content is treated as untrusted. Prompt injection attempts in Jira descriptions are fenced and neutralized before reaching the agent context.
|
|
|
|
## 6. Observability
|
|
|
|
Sync operations emit audit events to `~/.cowork_local/audit/YYYY-MM-DD.jsonl`:
|
|
|
|
* `jira_knowledge.sync.started`: Sync initiated.
|
|
* `jira_knowledge.sync.completed`: Sync finished successfully (includes counts/duration).
|
|
* `jira_knowledge.sync.failed`: Sync failed (includes error code).
|
|
|
|
## 7. Troubleshooting
|
|
|
|
### 403 Forbidden
|
|
* **Cause**: Invalid credentials or insufficient permissions.
|
|
* **Fix**:
|
|
* **Cloud**: Ensure you are using an API Token, not your password.
|
|
* **Server**: Ensure you are using a valid Personal Access Token (PAT). If PAT fails, try Basic Auth with your actual password (some older servers require this).
|
|
* Check that your user has "Browse Projects" permission for the target Jira project.
|
|
|
|
### "Jira Project Knowledge is not configured"
|
|
* **Cause**: No project mapping found for the current identity.
|
|
* **Fix**: Ensure the `cowork_project_id` in the mapping matches the project selected in Cowork.
|
|
|
|
### Sync Fails / Timeout
|
|
* **Cause**: Network issues or large project size.
|
|
* **Fix**: Check network connectivity to Jira. The sync has a timeout of 20s per request. For very large projects, the initial sync may take time; subsequent incremental syncs are faster.
|
|
|
|
## 8. File Structure
|
|
|
|
* `~/.cowork_local/config.json`: Stores `jira` connection settings and `jira_knowledge` mappings.
|
|
* `~/.cowork_local/jira_kb/<project_id>/issues/`: Indexed canonical issues (JSON).
|
|
* `~/.cowork_local/jira_kb/<project_id>/manifest.json`: Sync state (last sync time, cursor).
|
|
* `~/.cowork_local/audit/`: Audit logs.
|
|
|
|
## 9. Known Limitations
|
|
|
|
* **Lexical Search**: Current retrieval uses term-overlap scoring, not semantic embeddings. It works well for exact terms and keywords but may miss conceptual synonyms.
|
|
* **Manual Sync**: Incremental sync is not yet scheduled automatically; it must be triggered via "Sync Now" or CLI.
|
|
* **Rich Text**: Complex Jira rich text (ADF) is simplified to plain text placeholders. |